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PREFACE 


This manual describes the BASIC-PLUS programming language as implemented for the RSTS/E operating system. 
Information is organized for the benefit of the beginning programmer, allowing the reader to gradually acquire 
increased programming capabilities. 


The BASIC-PLUS language is an extension of BASIC’ as originally developed at Dartmouth College. However, BASIC- 
PLUS offers many features not found in standard Dartmouth BASIC-PLUS or many other versions of BASIC-PLUS. 


Part I (Chapters 1, 2, 3) describes the RSTS/E system, its hardware and user features, and the simplest level of the 
BASIC-PLUS language. BASIC-PLUS as described here is essentially (but not exclusively) Dartmouth BASIC as 
originally developed. 


Part II (Chapters 4 through 8) describes some of the advanced features of BASIC-PLUS. The reader will find references 
to some of these additional capabilities in Part I. 


Part III (Chapters 9 through 12) describes the complete range of BASIC-PLUS data handling, including data storage, file 
I/O, the virtual storage concept and information on particular I/O devices. The appendices review the BASIC-PLUS 
language in summary form, and provide a list of RSTS/E error messages that BASIC-PLUS users are apt to encounter. 


As a language, BASIC-PLUS is easy to learn. Although BASIC-PLUS provides many advanced features for the more 
experienced programmer, it does not penalize the beginning user. Most problems can be solved on at least a rudimentary 
level using the statements described in Part I. The BASIC-PLUS statements and features described in Parts II and III 
allow more efficient code that uses less machine time and memory space, as well as more sophisticated data handling 
and output. 


The content of this manual pertains only to the writing and execution of correct programs in the BASIC-PLUS language. 
A description of the various RSTS/E commands (NEW, OLD, LIST, RUN, SAVE etc.) can be found in the RSTS/E Sys- 
tem User’s Guide. 


There are two modes of BASIC-PLUS operation: NO EXTEND mode and EXTEND mode. In EXTEND mode, certain 
features are available to the user that are not available in NO EXTEND mode; also, the syntax requirements are stricter 
in EXTEND mode. In general, descriptions of features should be assumed to apply to both EXTEND and NO EXTEND 
unless stated otherwise. All BASIC-PLUS coding examples are written in NO EXTEND mode, except those specifically 
designed to illustrate EXTEND mode features. 


For information on all of the current manuals pertaining to RSTS/E operation, consult the RSTS/E Documentation 
Directory. 


BASIC isa registered trademark of the Trustees of Dartmouth College. BASIC stands for Beginner’s All-purpose Symbolic Instruction 
Code. In this manual, the term BASIC-PLUS is used to refer to the BASIC language as specifically implemented for RSTS/E; when the 
term “BASIC” is used, it refers to the language in the generic sense. 
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PART I 


This first part introduces the RSTS/E system and the BASIC-PLUS programming language. Chapter | orients the user to 
the overall RSTS/E environment and to the notation conventions used in the manual. Chapter 2 analyzes an example 
BASIC-PLUS program to show the fundamental rules of program syntax. Chapter 3 describes the simple BASIC-PLUS 
program statements. After reading Part I, the user should have a sound introduction to the language, and be able to solve 
most programming problems. The extent to which Parts II and III will be studied depends largely on individual need and 
inclination. 


CHAPTER 1 
AN INTRODUCTION TO RSTS/E BASIC-PLUS 


1.1 INTRODUCTION TO PROGRAMMING 
For the benefit of the new programmer there are four phases in programming a computer: 


1. Defining the problem 

2. Designing, writing, and documenting the program 
3. Entering, testing, and debugging 

4. Using and maintaining the finished program 


BASIC-PLUS is one language in which the user can write programs designed for the RSTS/E system. The completed 
program is generally introduced from a terminal keyboard connected to the RSTS/E system. A program can be input 
through various peripheral media, such as paper tape, magnetic tape, DECtape, or punched cards; however, the initial 
creation of a BASIC-PLUS program is usually performed on-line to the computer from the terminal keyboard. 


Ideally a program runs correctly as written. In practice this is seldom the case. A program can contain simple typing 
mistakes or complex logical errors. Typing and syntactical errors are detected as the program is typed at the keyboard 
and appropriate error messages are printed. Other errors cannot be detected until the user attempts to run the program. 
Program errors are corrected on-line from the terminal keyboard. 


The testing and debugging process is continued until the program appears to produce the correct results. This is a good 
time to explain to the new user that a computer program only does what the programmer has instructed (not what he 
meant to instruct). Thus the actions performed by the computer do not necessarily produce the correct results. In 
order to obtain correct results from a computer, the user must write a program free of format errors that performs the 
desired computations correctly. 


RSTS/E provides keyboard commands which enable the user to create and execute a program, and then to save the pro- 
gram within the system for later retrieval and execution or modification. This saving process is known as storing or filing 
the program, and a BASIC-PLUS program saved in this fashion is called a program file. 


1.2 INTRODUCTION TO TIME-SHARING 
RSTS/E is a time-sharing system. This means that when a user is working with RSTS/E, he is probably sharing the system 
with other users, but the other users are not visible to him so far as the operation of the terminal is concerned. 


Many users can be on-line to RSTS/E at one time because RSTS/E controls the scheduling of program execution. User 
programs are brought into memory from disk, allowed to execute for a short time, and returned to disk. This process is 
called swapping. RSTS/E records the point in the program at which execution interruption occurs, and is able to resume 
operation at that point. 


Each user is allotted a block of memory between 2K’ and 16K for storage of a particular program. This block is swapped 
between memory and disk. If only one user job is active in the system at a given time, that job is allowed to execute 
without interruption until another program is ready. 


‘The term “K” refers to 1024 (decimal) words of storage in a computer. Hence, 2K = 2048 words and 8K = 8192 words. 
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1.3 THE BASIC-PLUS PROGRAMMING LANGUAGE 

BASIC-PLUS is one of the simplest of all programming languages because of its small number of powerful but easily 
understood statements and commands and its easy application to problem solving. The wide use of BASIC in scientific, 
business, and educational installations attests to its value and straightforward application. (See the bibliography at the 
end of this manual for a list of BASIC texts and other elementary computing texts.) 


BASIC is similar to other programming languages in some respects but is especially suited for time-sharing because of its 
conversational nature. A conversational language is one that allows the user to communicate with the language processor 
by typing on the terminal keyboard. BASIC responds by printing on the terminal. This provides an interactive man/ 
machine relationship. 


BASIC-PLUS contains both elementary statements used to write simple programs and advanced programming features 
and statements to produce more complex and efficient programs. The key word here is efficient. As the user progresses 
and gains programming experience, he will naturally find himself becoming more efficient and able to use more sophis- 
ticated data manipulations. Almost any problem can be solved with the simple BASIC-PLUS statements. Later in the 
user’s programming experience, the advanced techniques can be added. 


1.4 CONVENTIONS USED IN THIS MANUAL 
Certain documentation conventions are used throughout this manual to clarify examples of BASIC-PLUS syntax.! Each 
BASIC-PLUS statement is described at least once in general terms using the following conventions: 


1. Items in lower case type (formula, variable, etc.) are supplied by the user according to rules explained in the 
text. Items in capital letters (LET, IF, THEN, etc.) must appear exactly as shown because they form the 
vocabulary of the BASIC-PLUS language; i.e., they are BASIC-PLUS keywords. 

2. Angle brackets << > indicate essential elements of the statement of command being described. For 
example: 


{LET <variable> = <expression> 


3. Square brackets [ | indicate a required choice of one element among two or more possibilities. For 
example: 


| THEN <statement> 
IF <expression> |THEN <line number> 
GOTO <line number> 


4. Braces | indicate an optional statement element or a choice of one element among two or more optional 
elements: 


IF <expression> |THEN <line number> 


GOTO <line number> 


THEN <statement> 
ge <line number> 


ELSE <statement> 


The use of some terms in this document may be unfamiliar to the new user. The following definitions and explanations 
are valid throughout this manual: 


1. BASIC-PLUS prints on the terminal whereas the user types on the keyboard. 
2. A statement is a single BASIC-PLUS language instruction identified by one or more BASIC-PLUS language 
keywords characteristic of the syntax for that instruction. 


' The syntax of a language is the set of rules governing the combination and ordering of language elements. 
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3. A BASIC-PLUS program line consists of a line number, followed by one or more BASIC-PLUS language 
Statements entered over one or more terminal lines. A program line is terminated by a RETURN key. A 
program line may contain one or several statements separated by backslashes (see Section 2.4.1). For 
compatibility with past versions, a colon is allowed in place of the backslash. 


A BASIC-PLUS terminal line consists of a set of BASIC-PLUS statements, or portions thereof, entered on 
one physical line, that either by itself or in combination with other terminal lines constitutes a BASIC- 
PLUS program line. 


The first terminal line of a program line must begin with a line number. Each continued terminal line must 


be terminated by a LINE FEED key or, if EXTEND mode is current, by an ampersand character followed 


by a RETURN key. The last terminal line of a program line must be terminated by a RETURN key with n°: 


preceding ampersand character. 

4. Commands cause BASIC-PLUS or a system program to perform some operation immediately and are not 

preceded by a line number. A command is terminated by typing the RETURN key. 

. A user program consists of a series of statements written in the BASIC-PLUS language. 

6. There is no standard RSTS/E terminal. RSTS/E can accommodate a wide variety of terminals such as a 
DECwriter II (LA36), VTOS display, VT50 or VT52 DECscope. All terminals have a keyboard and 
either a printer or cathode ray tube (CRT) screen. The RSTS/E user terminal is referred to as terminal, 
display, teleprinter, or keyboard, depending upon whether a part or the whole device is indicated. The use 
of terminals and other peripheral devices is described in the RSTS/E System User’s Guide. 


Nn 


7. The term BASIC-PLUS indicates the BASIC-PLUS language, the BASIC-PLUS Interpreter (the system pro- 


gram which accepts and executes BASIC-PLUS programs) or both, depending on the context of usage. 
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CHAPTER 2 
FUNDAMENTALS OF PROGRAMMING IN BASIC-PLUS 


2.1 MODE SELECTION (EXTEND VS. NO EXTEND) 

There are two program modes: EXTEND and NO EXTEND. All programs written for versions of BASIC-PLUS prior to 
RSTS/E VO6B operate under NO EXTEND. The user can switch modes at any time on either the command or the pro- 
gram level. Immediately following log-in, the system is in NO EXTEND mode, so that programs written in NO EXTEND 
mode can be executed without any special action by the operator. 


When operating in EXTEND mode, the user has access to several features that are not available in NO EXTEND. How- 
ever, format requirements are somewhat more stringent; in NO EXTEND, spaces and tabs are ignored by the compiler 
except in string constants. In EXTEND mode, blanks and tabs are syntactically significant. EXTEND mode features will 
be described throughout the manual. 
All examples are shown in NO EXTEND mode except those specifically designed to show EXTEND mode features. 
To enter EXTEND mode at the command level, the user types: 

EXTEND 
To switch from EXTEND to NO EXTEND mode, the user types: 

NO EXTEND 

or 
NOEXTEND 


There is no effect if the command entered names the current mode. 


Mode switching is possible at the program statement level. To do this, precede the EXTEND or NO EXTEND command 
with a line number. For example: 


10 EXTEND 
or 
10 NOEXTEND 


In general, it is not good programming practice to switch modes repeatedly within a program. Recommended usage is to 
include an EXTEND or NO EXTEND statement at the beginning of a program to ensure that it is compiled under the 
proper mode. 


2.2 EXAMPLE BASIC-PLUS PROGRAM 

The program in Figure 2-1 is an example of a user program written in the BASIC-PLUS language. It illustrates syntax 
and elements of the language as well as standard formatting of statements and the appearance of terminal output. Even 
one who has never studied BASIC can probably gather what the program does and understand at least vaguely how it 
works. 
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LISTNH 


100 


110 


1490 
L150 

32767 

Ready 


RUNNH 


THIS FROGRAM GIVES RANDOM DICE 
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RANDOMIZE 
THIS IS A RANDOM DICE ROLL ROUTINE 


! 

| 

| 
PR 


\ AZ=CINTCOXRNDD + 


UNITE Fy 
INT 
PRINT 
INFUT 
PRINT 
INFUT 
FRINT 
INFUT 


KO J=1 


“THIS FROGRAM GIVES 


THE USER CAN SFECIFY HOW MANY DICE TO BE IN 
EACH ROLL 
WHETHER TO FRINT THE 


ANI) HOW MANY ROLLS ARE TO BE MATE, 
TOTAL OF EACH ROLL IS ALSO 
USER CONTROL 

RANDTOM DICE ROLLS’ 


“HOW MANY DIES IN EACH ROLL’ 3 


\ BA=AZ + BAZ 
\ FRINT Ads 


‘NEAT 


LF 
FR 
\ 


ee ee, 


Rb = 
INT 
B%=0 


ENT 


N 
“HOW MANY ROLLS” » 
[l 
“ITF YOU WANT THE TOTAL OF EACH ROLL» TYFE Y’s 
Fe 
TO 0 
“THE ’9Ne “DIES OF ROLL’ + Js “ARES %» 
TO N 
=. 
et THER PRA <-=-TOLaL OF Rut =" see 


ROLLS 


HOW MANY DIES IN EACH ROLL? & 
HOW MANY ROLLS? 3 


IF YOU WANT 


THE 


Ci 


THE.-o 


THE 3 


Ready 


RUNNH 


THIS FROGRAM GIVES RANDOM DICE 


THE TOT Al OF BACH ROLIs TYPE Yet 
DIES OF ROLE t- ARE? 4. 2 AA. 3 =A a 7 
DIi£S GF ROLL 2 ARES 6 3 1 4 9 re re ed 
bIES OF WELL 3 ARESS 3-24" 64. > ——fe ra GF est = 


ROLLS 


HOW MANY DIES IN EACH ROLL? 2 
HOW MANY ROLLS? 
IF YOU WANT THE 


THE 


—{ 
it te 
iT} 

PI hI hI hh 


7 
1) 
38) 
o 
ta 


DIES 
BiES 
RIES 
DIES 
DIES 


i 
vd 


TOTAL OF EACH ROLL, TYFE Y? N 
Ur ROLE 1 AKES- 2 3S 
OF ROLL 2 ARE? 4 4 
OF ROLL 3 AREs 4 3 
OF ROLL 4 ARE: 3 6 
OF ROLE 9 ARES 3° S 


Figure 2-1 Sample BASIC-PLUS Program 
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A user program is composed of lines of statements containing instructions to BASIC-PLUS. Each line of the program 
begins with a line number, followed by one or more BASIC statements. Line numbers indicate the sequence of state- 
ment execution, although this sequence can be interrupted by certain statements. Each statement begins with a word 
specifying the type of operation to be performed, such as printing, data input, a determination of a condition, ora 
change of the contents of a variable. If a program line contains multiple statements, those statements must be separated 
by backslash characters. 


2.3 LINE NUMBERS 
Each BASIC-PLUS program line is preceded by a line number. Line numbers perform the following: 


1. Indicate the order in which statements are normally evaluated. 

2. Enable the normal order of evaluation to be changed; that is, the execution of the program can branch or 
loop through designated statements (this is explained further in the sections on the GOTO, GOSUB, and 
IF-THEN statements in Chapter 3). 

3. Enhance program debugging by permitting modification of any specified program line without affecting any 
other portion of the program. 


Line numbers are in the range of 1 to 32767. BASIC-PLUS maintains programs in line number sequence, rather than the 
order in which lines are entered to the system. It is good programming practice to number lines in increments of 5 or 10 
when first writing a program, to allow for insertion of lines when debugging or enhancing the program. 


A program line can have more than one statement. The first statement on a program line must be preceded by a line 
number, and each subsequent statement must be preceded by a backslash (\). Also, a program line can be continued 
over several physical terminal lines as long as no integral BASIC elements (e.g., key words, constants, variable names) 
are broken. 


Using multiple statements and multiple terminal lines in a program line saves memory space. It does make debugging and 
editing of a program more difficult, however. 


NOTE 
For compatibility with programs written for earlier versions 
of BASIC, RSTS/E accepts the colon (:) as a valid statement 
separator. 


When a program is executed (with the use of the RUN command), the BASIC-PLUS processor evaluates the statements 
in the order of their line numbers, starting with the smallest line number and going to the largest. 


2.4 STATEMENTS 

Each line number is followed by a BASIC-PLUS statement. The first word of a BASIC-PLUS statement identifies the 
type of statement and informs BASIC-PLUS of the operation to be performed and how to treat the data (if any) that 
follows the word. 


2.4.1 Multiple Statements on a Single Line 
More than one statement can be written on a single line as long as each statement (except the last) is terminated with a 
colon or a backslash. Only the first statement on a line can (and must) have a line number. For example: 
LO INFUY AsBs€ 
is a Single statement line. However: 


20 LEY X=xti 4 PRINI Xe¥eZ2 \ Ik ¥=2_- GOTO 20 


is a multiple-statement line containing three statements: a LET, a PRINT, and an IF-GOTO statement. 
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Any statement can be used anywhere in a multiple-statement line except as noted in individual statement descriptions. 


2.4.2 Line-to-Line Statement Continuation 

A statement can be continued on successive lines of the program. To continue a statement in NO EXTEND mode, press 
the LINE FEED key instead of the RETURN key. The LINE FEED performs a carriage return/line feed operation on the 
terminal and the continuation line does not contain a line number. For example: 


10 LET W?=(W-X4K3) KC Z-AZ 
(A~B-17) 


This is equivalent to: 
LO LET W2=CW-X4k35 KC Z-A/CA-BI 17) 


To continue a statement in EXTEND mode, type an ampersand at the end of the line and then press RETURN. Any 
number of tabs and space characters are allowed between the ampersand and the RETURN. The line feed method used 
in NO EXTEND is valid in EXTEND, but the syntax 


&[tabs/spaces] ( R&T _) 


is recommended to ensure compatibility with future versions of BASIC-PLUS. For example: 


10 EXTENT 

200 LEY TOTAL .RECEIFTS = 
GROCERTIES.IN + 
QELI.IN + 
PRODUCE. IN + 
QAIRY.IN + 
MEAT.IN + 
FARPERBACKS. IN 


RO RS RO RO RC RC 


The LINE FEED and RETURN keys do not cause a printed character to appear on the page. 
There is no limit to the length of a multiple-line statement in either mode. 


Where line continuation is used, it must occur between the integral elements of a BASIC-PLUS statement. Examples of 
BASIC-PLUS elements are a BASIC-PLUS language keyword, an alphanumeric string, a variable name, or a line number. 
No integral element can be interrupted at the end of one line and continued on another. For example: 


10 IF Al=0 
THEN 100 


is acceptable where a continuation follows 0. However, 


10 IF &A 
1=0 THEN 100 
?Plllesel conditional clause at Line 190 


is not acceptable. Neither is: 
10 IF Al=0O THEN 1 


OO 
?TModifier error et line 10 
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Each illegal form generates an error message. A number of multiword phrases are processed as one keyword and cannot 
be broken by a line continuation. 


These phrases are: 


GO TO AS FILE MAT READ 
GO SUB FOR INPUT AS FILE MAT PRINT 
ON ERROR FOR OUTPUT AS FILE MAT INPUT 
ON ERROR GO. TO NO EXTEND MAT LET 
INPUT LINE 


Blanks within these phrases may be omitted. For example, GOTO is equivalent to GO TO. 


2.5 SPACES AND TABS 
In NO EXTEND mode spaces can be used freely throughout the program. 


In EXTEND mode, however, spaces are significant, and can be used only between BASIC-PLUS language elements and 
in alphanumeric strings. Moreover, spaces are required to delimit elements that are not otherwise delimited by a 
character not in the set of characters that is valid for EXTEND mode variable names (see 2.6.2). For example, consider 
the following statement lines: 

(A) .10 LEt x= YX2- + 4 

(B) 1LOLETX#Y¥X2t1 

(C) 10 Bes ee ee Ee FF 
In NO EXTEND mode the above statements are identical in effect. 
In EXTEND mode, however, only (A) is valid. (B) requires a space between LET and X; all other elements are properly 
delimited by arithmetic symbols. In (C) the keyword LET contains imbedded spaces, which must be removed, and, as in 
(B), LET and X must be separated by spaces. Note that any number of spaces can follow or precede an element. 


Tabs, like spaces, can make a program easier to read. For example: 


@9OQO FOR K=1 TO 3 


2O19O FOR I=1 TO 10 

ZOO FOR J=1 TO 10 

2 O4D ACTsJ) = R/CItI-LItACT sD 
2 O80 NEXT J 

2OQSO NEXT I 


2O70O NEXT I 
32767 ENT 


2.6 EXPRESSIONS 


An expression is a group of symbols which can be evaluated by BASIC-PLUS. Expressions are composed of constants, 
variables, functions, or a combination of the preceding separated by arithmetic, relational, or logical operators. 
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The following are examples of expressions acceptable to BASIC-PLUS: 
Arithmetic Expressions 


5.135 
4% + Z% 
A7*(B 2% +1.) 


Relational Expressions 


AY 
Y9% > 0% 
A% =B 


Logical Expressions 


(A <0.) AND (B= 1.) 
((A > B) OR (C =D)) AND A/B< > C/D 


Arithmetic expressions yield either floating-point or integer values. Relational expressions yield a truth value that 
reflects the result of comparing two values. Logical expressions yield a truth value reflecting the existence or non- 
existence of a specified set of relational or other conditions. 


A constant or a variable name with no % or $ suffix indicates a floating-point value. Floating point values are stored in 
either a 2-word or 4-word floating point format, depending on the type of math package installed. 


A constant or variable name with a contiguous % suffix indicates an integer value. An integer value is stored in a single 
word as a base 2 integer. Chapter 4 describes arithmetic operations, and Appendix E describes integer and floating point 
formats. Example: 


Floating Point Integer 
A A% 
9. 9% 
B3. +5. B3% + 5% 
3.1416 3.1416% (stored as 3%) 


The use of an explicit decimal point or percent sign is recommended in all numeric constants to avoid unnecessary data 
conversions and to improve documentation. Mixing of data types in a statement should be avoided and integers should 
be used whenever possible. When raising to an integer power, the power value should be indicated explicitly as an integer. 
Raising a floating point number to an integer power does not constitute mode mixing. (However, some examples in this 
manual do not follow these suggestions, in the interest of readability.) 


Another type of expression not described in detail in this section is the string expression, a value that consists of a 
sequence of characters, each character occupying a byte (i.e., one half of a memory word). A string expression can be 
expressed either as a constant (a sequence of characters enclosed in quotation marks) or as a variable (a variable name 
with a $ suffix). 


String expressions and operations are described in detail in Chapter 5. 


Not all kinds of expressions can be used in all statements, as is explained in the sections describing the individual state- 
ments. In the following sections the reader is introduced to the elements which compose BASIC-PLUS expressions. 
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2.6.1 Numeric Constants 
Numeric constants retain a constant value throughout a program, and can be positive or negative. Numeric constants can 
be written using decimal notation as follows: 


+2 
07S 
1234.56 
—123456 
—.000001 


The example constants would be stored as floating point, since they have no % suffix. 


Scientific notation allows further flexibility in number representation. Numeric constants can be written using the 
letter E to indicate “‘times 10 n’’; the number following the letter E indicates the exponent n. 


000123456 can be written in BASIC-PLUS as 123456E-6 
1234560000. can be written in BASIC-PLUS as 123456.E4 
-12345678900. can be written in BASIC-PLUS as - 1.2345679E10 


The E format representation of numbers is very flexible since a number such as .OO1 can be written as 1E-3, O1E-1, 
1O0E-5, or any number of ways within the allowable range of exponents. If more than six digits are generated during 
any computation, the result of that computation is automatically printed in E format. (If the exponent is negative, 

a minus sign is printed after the E; if the exponent is positive, a space is printed: 1E-04; 1E 04.) 


The combination E7, however, is not a constant, but a variable. The term 1E7 is used to indicate that 1 is multiplied by 
10 7,i.e., the number 10000000. 


The set of floating-point numbers is approximately as follows: 
X =0, and the range 10°38< |x| <10%38 
The range of integer numbers is —32768 through 32767. 


2.6.2 Numeric Variables 
A variable is a data item whose value can be changed during program execution. A numeric variable is denoted by a fixed 
variable name. 


In NO EXTEND mode, a variable name consists of a single letter or a single letter followed by a single digit. In EXTEND 
mode a variable name consists of a single letter followed contiguously by 0 to 29 characters from the set: 


A eS (letters) 
28 es (digits) 
(period or point) 


A name can also have an FN prefix (denoting a function name), a % suffix (denoting an integer), a $ suffix (denoting 
a string), or a subscript suffix that consists of a set of subscripts enclosed in parentheses. These prefixes and suffixes 
are not counted in the 30-character limit. 


Variables are assigned values by LET, INPUT, and READ statements. The value assigned to a variable does not change 


until the next time a LET, INPUT or READ statement is encountered that contains a new value for that variable or 
until the variable is incremented by a FOR statement. (These conditions are explained further in later sections.) All 
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variables are set equal to 0 before program execution. It is necessary to assign a value to a variable only when an initial 
value other than 0 is required. However, it is good programming practice to set variables equal to 0 wherever necessary. 
This ensures that later changes or additions will not cause misinterpretation of values. 


2.6.3 Mathematical Operators 

BASIC-PLUS automatically performs the mathematical operations of addition, subtraction, multiplication, division and 
exponentiation. Formulas to be evaluated are represented in a format similar to standard mathematical notation. There 
are five arithmetic operators used to write such formulas, as follows: 


Operator Example Meaning 
= A+B Adds B to A 
= A-B Subtracts B from A 
. A*B Multiplies A by B 
/ A/B Divides A by B 
= A’B Calculates A to the B power, AB 


BASIC-PLUS permits the operator ** in place of = (up arrow) to denote the exponentiation operation. For example: 
AT*B 


indicates the quantity A raised to the B power, equivalent to AB. The ** operator is included for compatibility with some 
other BASIC processors. The symbol “ is the standard BASIC-PLUS symbol for exponentiation and is used throughout this 
manual. 


Unary plus and minus are also allowed, e.g. the - in- A+B or the + in +X-Y. Unary plus is ignored. Unary minus is treated 
as explained below. 


When more than one operation is to be performed in a single formula, rules are observed as to the precedence of the above 
operators. The arithmetic operations are performed in the following sequence, with the operation described in item 1 
having precedence. 


1. Any formula within parentheses is evaluated before the parenthesized quantity is used in further computations. 
Where parentheses are nested, as follows: 


(A+(B*(D 2))) 


the innermost parenthetical quantity is calculated first. 
2. In the absence of parentheses in a formula, BASIC-PLUS performs operations as follows: 


Exponentiation 

Unary minus 
Multiplication and division 
Addition and subtraction 


ao cp 


Thus, for example, -A’B with a unary minus, is a legal expression and is the same as -(A “B). This implies 
that -2° 2 evaluates as -4. The one exception to this rule is that the term A —B is allowed and is evaluated 
as A ze B). 


3. In the absence of parentheses in a formula involving more than one operation on the same level (see item 2 
above), the operations are performed left to right, in the order that the formula is written. For example: 
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A/B/C is evaluated as (A/B)/C 
A*B/C is evaluated as (A*B)/C 


The expression A+B*C_ D is evaluated in the following order: 


1. C is raised to the D power 
2. The result of the first operation is multiplied by B. 
3. The result of the previous operation is added to A. 


Parentheses are used to indicate any other order of evaluation. For example, to raise the product of B and C to the D power, 
the user writes the expression as follows: 


A+(B*C) D 
To multiply the quantity A+B by C to the D power, the user writes the expression as follows: 
(A+B)*C D 


The user is encouraged to use parentheses even where they are not strictly required in order to make expressions easier 
to read and to reduce the possibility of writing an unintended expression. 


2.6.4 Relational Symbols 

Relational symbols are used in IF-THEN statements (see Section 3.5): in conditional FOR loops (see Section 8.6); in IF, 
UNLESS, WHILE and UNTIL clauses (see Sections 3.5, 8.5, and 8.7) where it is necessary to compare values; and where 
any integer expression can be used (see Section 6.6). The relational symbols are as follows (where A and B are numeric 
variables or expressions): 


Mathematical BASIC-PLUS 

Symbol Symbol Example Meaning 
- A=B A is equal to B 
< A<B A is less than B 
< A<=B A is less than or equal to B 
3 A>B A is greater than B 
ee A>=B A is greater than or equal to B 
- A<>B A is not equal to B 
~ ==B A is approximately equal to B 


The term “‘approximately equal to” means that the two quantities look the same when printed to six decimal places of 
precision. Within the computer, floating-point numbers with a fractional part can differ by a miniscule amount in the 

last decimal place but still be considered equal for all practical purposes. This last decimal place within the computer does 
not always cause two numbers to have a different value when printed. Numbers are carried internally at greater than 

6 digits of precision, but are rounded to 6 digits for output or a comparison. Thus, two numbers identical when rounded 
to 6 digits of precision are approximately equal, whereas two numbers equal to the internally carried limits of precision 
are truly equal (=). 
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2.6.5 Logical Operators 

Logical operators are used in IF-THEN and such statements (see Section 3.5) where some condition is used to determine 
subsequent operations within the user program. For this discussion, A and B are relational expressions having only TRUE 
(-1) and FALSE (0) values. Logical operators can also be used in certain logical operations involving integers. (See 
Sections 6.5 and 6.6.) The logical operators are as follows: 


The logical negative of A. If Ais true, NOT A is false. 


The logical product of A and B. A AND B has the value true 
only if A and B are both true and has the value false if either 
A or Bis false. 


The logical sum of A and B. A OR B has the value true if either 
A or B or both is true and has the value false only if both A and 
B are false. 


The logical exclusive OR of A and B. A XOR B is true if either A 
or B (but not both) is true, and false otherwise. 


The logical implication of A and B. A IMP B is false if and only 
if A is true and B is false; otherwise the value is true. 


A is logically equivalent to B. A EQV B has the value TRUE if A 
and B are both true or both false, and has the value false otherwise. 


The following tables are called truth tables and describe graphically the results of the above logical operations with both 
A and B given for every possible combination of values. 


A NOT A 


Th ry 
ra) 
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ELEMENTARY BASIC-PLUS STATEMENTS 


This chapter describes the simplest forms of the more elementary BASIC-PLUS statements. These statements are suffi- 
cient, by themselves, for the solution of most problems. Once these statements are mastered, the user can investigate the 
more advanced applications of these statements and the additional statements and features explained in Parts II and III. 


The reader should understand that any problem which can be solved with the more advanced techniques can also be 
solved with the simpler statements, although the process may not be as efficient. As long as the user understands the 
details of his problem he can represent it in BASIC-PLUS on a number of levels ranging from the simple to the 
sophisticated. 


3.1 REMARKS AND COMMENTS 

It is often desirable to insert notes and messages within a user program. Information such as the name and purpose of 
the program, how to use it, how certain parts of the program work, and expected results at various points is useful in 
the program for ready reference by anyone using that program. 


There are two ways of inserting comments into a user program: 


1. Using the REM statement 
2. Using the exclamation mark (!) 


REM statements can contain any printing characters on the keyboard, except that in EXTEND mode the word REM must 
be followed by a space or other valid word delimiter. BASIC-PLUS completely ignores anything on a line following the 
letters REM. (The line number of a REM statement can be used in aGOTO or GOSUB statement, see Sections 3.4 and 
3.8.1, as the destination of a jump in program execution.) Typical REM statements are shown below: 


LQ REM ~- THIS FROGRAM COMPUTES THE 
Li REM ~- ROOTS OF A QUADRATIC EQUATION 


The exclamation mark is normally used to terminate the executable part of a line and begin the comment part of the 
line. The ! character can also begin the line, in which case the entire line is treated as a comment. For example: 


ies LET Ass ! FIRST VALUE OF A 
130 PRINT A“2 f TOES NOT CHANGE A 
140 | ENTIRE LINE IS COMMENTARY 


In every statement other than the DATA statement, BASIC-PLUS ignores everything on the line following the exclama- 
tion mark. An exclamation mark must not appear on the same program line as a DATA statement unless it is part of an 
item in the DATA statement. 


Messages in REMARK statements are generally called remarks, those after the exclamation mark, comments. Remarks 


and comments are printed when the user program is listed but do not affect program execution. (They do affect 
program size, however.) 
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The lines below indicate three ways of putting the same remark on two lines. Lines 10 and 11 are REM statements. 
Line 20 is one REM statement broken into two lines with the LINE FEED key. Line 30 is one comment (begun with 
a!) and broken into two lines with the LINE FEED key. Line 40 is one comment broken into two lines with the 
ampersand character followed by a RETURN key; this is legal only under EXTEND mode. 


10 REM -~ THIS FROGRAM COMPUTES THE Ce) 
ti REM ~ ROOTS OF A QUADRATIC EQUATION Cee) 
2 REM ~ THIS FROGRAM COMPUTES THE 
ROOTS OF A QUADRATIC EQUATION ( rer ) 
30 ! THIS PROGRAM COMPUTES THE 
ROOTS QF A QUADRATIC EQUATION Cer ) 
40 | THIS FROGRAM COMPUTES THE & C rer) 


f ROOTS OF A QUADRATIC EQUATION 


When a comment is continued on a subsequent terminal line with an ampersand and carriage return, the continuation 
line must also start with an exclamation point or it will be interpreted as an executable statement. For example: 


10 EXTEND 

20 (THIS FROGRAM COMFUTES THE & 
'ROOTS OF A QUADRATIC EQUATION & Ce) 
FRINT “ENTER THREE COEFFICIENTS’ 

RUNNH 

ENTER THREE COEFFICIENTS 


Ready 
3.2 LET STATEMENT 
The LET statement assigns a numeric value to a variable. Each LET statement is of the form: 


1 LET} <variable> = <expression> 


This statement does not indicate algebraic equality, but performs the calculations within the expression (if any) and 
assigns the numeric value to the indicated variable. For example: 


10 LET Sc Atl 
2 Q LET We = CA4-XSKCZ-ASB) 


In line 10, the old value of X is increased by 1 and becomes the new value of X. In line 20, the formula on the right-hand 


side is evaluated and the numeric value assigned to W2. 
The LET statement can be a simple numerical assignment, such as 
wO LET A=35 
or require the evaluation of a formula so long that it is continued on the next line (see Section 2.3.2). 


BASIC-PLUS allows the user to omit the word LET from the LET statement. The user may find it easier to type: 


10 X=12K¢(S5+7) 
than 
190 LET X=12*¢(St+7) 


This is a convenience and does not alter the effect of the statement. 


3-2 


(& 


—— 


rh] 


Elementary BASIC-PLUS Statements 


3.3.2 PRINT Statement 
The PRINT statement is used to output data onto the terminal teleprinter. The general format of the PRINT 
statement is: 


PRINT {list} 


where the list can contain expressions, text strings, or both. As the braces indicate, the list is optional. Used alone, 
the PRINT statement: 


pacts, PRINT 
causes a carriage return/line feed operation. 


PRINT statements can be used to perform calculations and print results. Any expression within the list is evaluated 
before a value is printed. Consider the following program: 


LIS TNH 
2 OOO LET A=1 \ LET B=2 \ LET C=3+A 
lOO PRINT 
22QQ PRINT AtBEC 
S22? ENT 
Rescdsy 
RUNNH 
7 
Ready 
All numbers are printed in the form: 
space 
<number> <space> 
The PRINT statement can be used anywhere in a multiple statement line. For example: 
1600 A&=1 \ FRINT A \ ABAtS \ PRINT \ FRINT A 


would cause the following to be printed on the terminal when executed: 


RUNNH 
‘ 


& 


Ready 
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Notice that the teleprinter performs a carriage return/line feed at the end of each PRINT statement. Thus the first 
PRINT statement causes a | and a carriage return/line feed, the second PRINT statement is responsible for the blank 
line, and the third PRINT statement causes a 6 and another carriage return/line feed to be output. 


BASIC-PLUS considers the terminal printer to be divided into zones of 14 spaces each. On most terminals the maximum 
print line contains 72 characters, in which case there are 5S print zones. Terminals with 84 or more print characters per 
line have additional print zones in units of 14 spaces. 


When an item in a PRINT statement is followed by a comma, the next value to be printed appears in the next available 
print zone. For example: 


LISTNH 

1500 LET A=3 \ LET B=2 

1LéO0 PRINT AvsBsAtHsAKKR»sA~BRyB-AvA Be BR” CRSA? 
32767 END 


Ready 
RUNANH 


3 a 
sa , 


i 
on 
towel 


ev 74 


fond, 


Ready 


Notice that the sixth element in the PRINT list is printed as the first entry on a new line, since a 72-character line has 


five print zones. 


Two commas together in a PRINT statement cause a print zone to be skipped. For example: 


LISTNH 

100 REM THIS SHOWS HOW TO SKIF A FRINT ZONE 
ANT SHOWS LINE CONTINUATION. 

119 LET A=] 


aes Je Beer 

\ FRINT Asks Atk 

INOTE DOUBLED COMMA AFTER & 
Bel? EO NXI 


Re ects 
RUNNEH 
t 2 3 


Ready 


If the last item in a PRINT statement is followed by a comma, no carriage return/line feed is output, and the next 
value to be printed (by a later PRINT statement) appears in the next available print zone. For example: 
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LISTNH 
100 REM THIS SHORT FROGRAM ILLUSTRATES FRINT FORMAT >» 
USING COMMA ANI SFACE 
110 LET A=] 
\ R=2 
\ C3 
120 ! IN LINE 110% NOTE USE OF BACKSLASH (\) TO PUT MULTIPLE 
! STATEMENTS ON ONE PROGRAM LINE’ THAT IS» ON ONE LINE 
! NUMBER. MINIMIZING THE NUMBER OF LINE NUMBERS RESULTS 
f IN MORE EFFICIENT CODE. EACH STATEMENT IS FLACED 
! ON ITS OWN FHYSICAL LINE BY USING LINE CONTINUATION. 
! TO CONTINUE A LINE IN EITHER EXTEND OR NOEXTEND MODE 
| PRESS FHE LINE FEED KEY. 
130 FRINT Ay 
140 FRINT B 
150 FRINT C 


| THE THREE FRINT STATEMENTS ARE ON SEPARATE 
! LINE NUMBERS. THIS IS LEGAL BUT LESS EFFICIENT. 
32767 END 


Ready 

RUNNH 
1 2 
Rs 

Ready 


If a tighter packing of printed values is desired, the semicolon character can be used in place of the comma. A semicolon 
causes no extra spaces to be output. A comma causes the print head to move at least one space to the next print zone or 
possibly perform a carriage return/line feed. The following example shows the effects of the semicolon and comma. 


LISTNH 
100 LET Asi] 
\ LET B=2 
(£4. 5 -E23 
110 PRINT AsBsCs 
120 FRINT Atis Btls C+i 
139 PRINT AsBsCs 
140 PRINT AtBtlsC°RsC" (BCC) 
130 FRINT 
160 FRINT 30210061508 20022502 300 
32767 ENT 
Reaecty 
RUNNH 
Oo ee oe ae ee 
1 2 3 & > 
S561 
rat @) 100) 615006200 20 300 
Ready 
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The PRINT statement can be used to print a message, either alone or together with the evaluation and printing of 
numeric values. Characters are delimited for printing by placing single or double quotation marks at each end of the 
string. The same type of quotation mark must be used at the beginning and the end of each string. 


LISTNH 


100 3 a OS Sees SS | ee ee S| oe 

110 FREINT “QUOTH THE RAVEN: "“NEVERMORE ° ’ 
Ug es EN 

Ready 

RUNNH 


TIME’S UF 
QUOTH THE RAVEN» “NEVERMORE® 


React 
As another example, consider the following line: 


wie X=O7- 4 


OQ FRINT “AVERAGE GRANDE IS’ 9x 
which prints the following: 

AVERAGE GRATE IS 87.4 
When a character string is printed, only the characters between the quotes appear; no leading or trailing spaces are added. 
Leading and trailing spaces can be added within the quotation marks using the keyboard space bar; spaces appear in 
the printout exactly as they are typed within the quotation marks. 
When a comma separates a text string from another PRINT list item, the item is printed at the beginning of the next 
available print zone. Semicolons separating text strings from other items are optional, but should be included for com- 
patibility with other versions of BASIC. 

at Le) FRINT “AVERAGE GRADE IS’ xX 
A comma or semicolon appearing as the last item of a PRINT list suppresses the carriage return/line feed operation. 


The following example demonstrates the use of the comma and semicolon as formatting characters. 
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LISTNH 
150 TINFUT “STUDENT NUMBER’ 5X 
L&G INPUT “GRATE? $6 
1/0 INFUT ‘AVERAGE’ 5A 
L8oO INFUT “RANK 7’ ok 
IRRELEVANT CORE OMITTED 
300 NeSG2 
&4O FRINY “STUDENT NUMBER’ Xs ‘GRADE =’G3 
650 PRINT “AVERAGE =’% A 
550 PRINT ¢ RANK IN CLASS‘’Rs: ‘OF’ WN 
setos ENT 
Ready 
RUNNH 


STUDENT NUMBER?P 2374 

GRAQNE? 8? 

AVERAGE? 90.6 

RANK? 14 

STURENT NUMBER 2574 GRADE = 89 AVERAGE = 90.6 
RANK IN CLASS 14 OF S62 


Ready 


3.3.3 INPUT Statement 

The second way to provide data to a program is with an INPUT statement. This statement is used when writing a pro- 
gram to process data to be supplied while the program is running. During execution, the programmer can type values as 
the computer asks for them. (Nonterminal INPUT is described in Part III.) Depending upon how many values are to be 
accepted by the INPUT command, the programmer may include a PRINT statement that reminds the user of the kind 
of input required. Such messages can also be generated from within the INPUT statement, as shown in the accompany- 
ing example. 


The INPUT statement is of the form: 

INPUT <list> 
For example: 

190 INFUT Ae Bel 
causes the computer to pause during execution, print a question mark, and wait for the user to type three numeric values 
separated by commas. The values typed are entered to the computer when the user presses the RETURN key, LINE 
FEED key, or the ESCAPE key (ESC on some terminals, ALT MODE on others). 
In the following example, the executing program requests data by asking four questions: INTEREST IN PERCENT?, 


AMOUNT OF LOAN?, NUMBER OF YEARS?, and NO. OF PAYMENTS PER YEAR?. The programmer knows which 
value is requested and proceeds to type and enter the appropriate value. 
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LISTNH 

10 REMARK ~- THIS FROGRAM COMFUTES INTEREST FAYMENTS 
20 INFUT “INTEREST IN FERCENT’ 5 J 

30 LET JJ7100 

AO INFUT “AMOUNT OF LOAN’ ¢& 

at @) INFUT “NUMBER OF YEARS’ #N 

bO TINFUT “NUMBER OF FAYMENTS FER YEAR’ ¢M 

7Q LET N=NXM \ I=J/M \ Bit! 

So LET R=AxXI/(€1-1/7B7N) 

9G PRINT 

106 FRINT “AMOUNT FER FAYMENT =’5 INTCRK107°2+.59/10°2 
110 FRINT ‘TOTAL INTEREST =o INTC CREN-AIK1O0°24+.5)9/1072 
L290 PRINT 

130 LET =A 

140 FRINT “INTEREST AFF TO FRIN BALANCE OF FRIN’ 
L300 LET EL=BxkI \o P=R-L. \ OUBeBH-P 

140 FRINT INTCL#X10°24+.5)/10" 2, 

1790 PRINT INTCPERKLIOT2S+.5)/10°2s 

180 FRINT INTCBK10°2+.5)/10°2 

190 IF Bz=RkR GOTO 150 

ZOO FRINT INTCCBKIIK1O°2+.579/10°25 INTCOCR-BRKIDK10°2+,.5)/10°2 
2Z1G FRINT “LAST PAYMENT =%s INTC CBRKI4+B) X107°2+.5)9/10°2 
B27 867 END 

Ready 

RUNNH 


INTEREST IN FERCENT? 10 
AMOUNT OF LOAN? 6000 

NUMBER OF YEARS? 1 
NUMBER OF FAYMENTS FER YEAR? 12 


AMOUNT FER FAYMENT 


wale 


i a 


TOTAL INTEREST 329.94 
INTEREST AFF TQ FRIN RALANCE OF FRIN 
wQ 4A? 7S pe be par ae 
4A&.O2 AS1.47 3941.03 
42.01 485449 4555-54 
3769S 489.53 4066.01 
33-88 493+61 357244 
2Pe?? 497.73 3074.67 
2062 YOL.87 20/208 
21.44 206406 2966.75 
17.22 J1LO.27 1556.47 
12.97 JL4ae G2 1941.95 
8.48 318.81 wesel4 
4.36 weoel4 


LAST FAYMENT 


Ready 
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As in the previous program, the question mark generated by BASIC-PLUS is grammatically useful if a printed question 
is to prompt the typing of the input values. 


The output for the program begins after the command RUNNH and includes a verbal description of the numbers. This 
verbal description on the output is optional with the programmer, although it has a definite advantage in ease of use 
and understanding. 


When the correct number of variables has been typed in answer to the printed ? character, pressing the RETURN key 
enters the values to the computer. If too few values are typed, the computer prints another ? to indicate that more 
data is requested. If too many values are typed, the excess data on that line is ignored. 


Messages to be printed at execution time can be inserted within the INPUT statement itself. The message is set off by 
single or double quotes from the other arguments of the INPUT statement. For example: 


100 INFUT “YOUR AGE IS ‘SA 


is equivalent to 
100 PRINT “YOUR AGE IS%s 
L116 INFUT A 


The use of the comma or semicolon character (or no character) to separate a character string to be printed from input 
variable names is analogous to the PRINT statement (see Section 3.3.2). 


3.4 UNCONDITIONAL BRANCH, GOTO STATEMENT 

The GOTO statement transfers program execution immediately and unconditionally to a specified program line; 
usually the specified line is not the next sequential line in the program. The general format of the statement is as 
follows: 


GOTO <Jine number> 


The line number to which the program jumps can be either greater than or less than the current line number. It is thus 
possible to jump forward or backward within a program. 


Consider the following example: 


LISTNH 
19 LET Az2 
= 60 FO -30 
40 LET A=SQRCAt14) 
30 FRINT AvAKA 
32767 ENT 
Re acy 
RUNNH 
2 4 
Reacts 


When the program encounters line 20, control transfers to line 50, After line 50 is executed, the program terminates. 
Line 30 is never executed. Any number of lines can be skipped in either direction. 


Elementary BASIC-PLUS Statements 


When written as part of a multiple statement line, GOTO should always be the last statement on the line, since any 
statement following the GOTO on the same line is never executed. For example: 


Ses LET A=ATNCIL) 110 LET AzATNCOLD 
\FRINT A \GO TO 379 
\G0._ 70.370 \FRINT A 
=r) PRINT “FINISHED? =] ee PRINT “FINISHED ’ 
BOF 6? ENT 9947 END 
BUNA RUAN H 
» “OG AFh KINTSHED 


FINTSHED 
Rie sty 
Re actu 


3.5 CONDITIONAL BRANCH, IF-THEN AND IF-GOTO STATEMENTS 

The IF-THEN and IF-GOTO statements are used to transfer conditionally from the normal consecutive order of state- 
ment numbers, depending upon some mathematical relation or relations. The basic format of the IF statement is as 
follows: 


THEN <statement> 
IF <condition> THEN <dine number> 
GOTO <dine number> 


The specified condition is tested. If it is false, control proceeds to the statement following the IF statement (the next 
sequentially numbered line). If the condition is true, the statement following THEN is executed or control is trans- 
ferred to the line number given after THEN or GOTO. (An extension of this statement, the IF-THEN-ELSE statement, 
is described in Section 8.5.) 


The deciding condition can be either a simple relational expression in which two mathematical expressions are separated 
by a relational operator, or a logical expression in which two relational or logical expressions are separated by a logical 
operator. For example: 


Relational Expression Logical Expression 


A+2 S38 A>B AND B<=SQR(C) 


Both types of condition, when evaluated, are either true or false; no numeric value is associated with the results of an 
IF statement. The relational and logical operators are described in Sections 2.6.4 and 2.6.5 and are presented in 
Appendix A for reference. 


ee TF AXBS=BRXCBR+1) THEN LET 04=04+1 


In the above line the quantities A*B and B*(B+1) are compared. If the first value is greater than or equal to the second 
value, the variable D4 is incremented by 1. If B*(B+1) is greater than A*B, D4 is not incremented and control passes 
immediately to the next line following line 75. 


When a line number follows the word THEN, the IF-THEN statement is the same as the IF-GOTO statement. The word 
THEN can also be followed by any BASIC-PLUS statement, including another IF statement. For example: 


wd Q If ASB THEN ITF BOC THEN PRINT *A>B>C* 
S50 IF ASB AND BSC THEN PRINT “’ASReC’ 


The preceding two lines are logically equivalent and perform the following operation: 
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if B is both less than A and greater than C, the message 
A>B>C 
is printed; otherwise the next line is executed. 


In the following example, the IF-GOTO statement in line 110 is used to limit the value of the variable A in line 100. 
Execution of the loop continues until the relationship A > 4 is true, then immediately branches to line 32767 to end 
the program. (A program loop is a series of statements which are written so that, when the statements have been 
executed, control transfers to the beginning of the statements. This process continues to occur until some terminal 
condition is reached.) 


LISTNH 


100 LET AsAtL 
\ X=AT? 
1190 IF A=4 GO TO 32767 
120 PRINT ‘°“X=’X; ‘s ANT VALUE OF A IS’ A 
13G GU 46-790 
32767 ENT 
Reach 
RUNANH 


X= J] » AND VALUE OF A IS 1 
X= 4 » AND VALUE QF A IS 2 
X= 9 » AND VALUE OF A IS 3 
X= 16 » ANT VALUE OF A IS 4 


Ready 


(The novice BASIC-PLUS programmer is advised to follow the operation of the computer through these short example 
programs.) 


In IF statements, the following priorities are associated with each operator, in order to provide unambiguous evaluation 
of the conditions specified (where item | has the highest priority): 


1. Expressions in parentheses 
2. Intrinsic or user-defined functions 
3. Exponentiation (*) 
4. Unary minus (- ), that is, a negative number or variable such as -3, - A, etc. 
5. Multiplication and division (* and /) 
6. Addition and subtraction (+ and - ) 
7. Relational operators (=, <<, <=, >, >=, ==, <>) 
8. NOT 
9. AND 
10. OR and XOR 
11. IMP 
12. EQV 


For each class of operators indicated above, operations proceed from left to right. 
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Examples of IF-THEN statements follow: 


100 IF ASB THEN 340 

2 OO ITF A=B OR B=C THEN 240 
300 TF ASE THEN A=-RB ! 
AOD LEAST IMP XZ THEN PRENT 


An IF statement would normally be the last statement on a multiple statement line (to avoid confusion); however, the 


CONDITIONAL ASSIGNMENT 
"QED" 


following rules govern the transfer path of the IF statement in other positions: 


1. The physically last THEN clause is considered to be followed by the next statement (or statements) on the 


line: 

LISTNH 

oO INFUT “ENTER A VALUE’ #4 

100 IF @A=1 THEN FRINT Ags 
\ PRINT “TRUE CASE’ 
\ GOTO 32767 

: Print ho = 4? 

weros ENG 

Ready 

RUNNH 

ENTER A VALUE? 2 

10S eee eee | 


Ri @ etc} y 

RUAN 

ENTER A VALUE? 1 
1 TRUE CASE 


Rescdy 


2. All other THEN clauses are considered to be followed by the next line of the program: 


LS TNH 


190 INFUY “ENTER AyBs AND C’ es Av Be oC 

2OO IF A=B THEN IF B>C THEN PRINT ‘A=C* 
Ve: - 2 S22 767 

Og SE PRINT “QOUBLE CONDITION NOT TRUE’ 

S2707 EN YI 

Rie atctty 

RUNANH 


ENTER AvBy AND CP 1293495 
NOUBLE CONDITION NOT TRUE 


Ready 

RUNANH 

ENTER AvyBy ANT CP 12394596 
ASC 

Ready 
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Only in the case where “A >C’” is printed is the statement GOTO 32767 executed. 


3.6 PROGRAM LOOPS 

Loops were first mentioned in the section of the IF-THEN and IF-GOTO statements. Programs frequently are 
designed to perform certain instructional sequences repetitively. Computers are particularly well suited for such tasks. 
With simple tasks, such as computing a list of prime numbers between | and 1,000,000, a computer can perform the 
operations and obtain correct results in a minimal 2zmount of time. To write a loop, the programmer must ensure that 
the series of statements is repeated until a terminal condition is met. 


Programs containing loops can be illustrated by using two versions of a program to print a table of the positive integers 
1 through 100 together with the square root of each. Without a loop, the first program is 101 lines long and reads: 


10 FRINT dy SQRC1) 

ea 8) PRINT 2» SQRC2) 

30 PRINT 3» SQR¢3) 

SPO FRINT 998 SQRC99) 
LOO0 PRINT 1009 SQRC100) 


32767 ENT 


With the following program example, using a simple sort of loop, the same table is obtained with fewer lines: 


10 LET X=] 

a FRINT X» SQRCX) 
30) LET X=X+] 

AQ IF X2#=100 THEN 20 


32/767 ENT 


Statement 10 assigns a value of | to X, thus setting up the initial conditions of the loop. In line 20, both the value of 
X and its square root are printed. In line 30, X is incremented by 1. Line 40 asks whether X is still less than or equal 
to 100; if so, BASIC-PLUS returns to print the next value of X and its square root. This process is repeated until the 
loop has been executed 100 times. After the number 100 and its square root have been printed, X becomes 101. 

The condition in line 40 is now false so control does not return to line 20, but goes to line 32767 which ends the 
program. 


All program loops have four characteristic parts: 


1. Initialization, the conditions which must exist for the first execution of the loop (line 10 above). 

2. The body of the loop in which the operation which is to be repeated is performed (line 20 above). 

3. Modification, which alters some value and makes each execution of the loop different from the one before 
and the one after (line 30 above). 

4. Termination condition, an exit test which, when satisfied, completes the loop (line 40 above). Execution 
continues to the program statements following the loop. 


3.6.1 FOR and NEXT Statements 
The FOR statement is of the form: 


FOR <variable> = <expression> TO <expression> | STEP <expression>} 
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For example: 
119 POR Res 10 20 -Sitt 2 


which causes program execution to cycle through the designated loop using K as 2, 4, 6, 8, ..., 20 in calculations 
involving K. When K=20, the loop is left behind and the program control passes to the line following the associated 
NEXT statement. The variable in the FOR statement, K in the preceding example, is known as the control variable. 


The control variable must be unsubscripted, although a common use of such loops is to deal with subscripted variables 
using the control variable as the subscript of a previously defined variable (this is explained in further detail in Section 
3.6.2). The expressions in the FOR statement can be any acceptable BASIC-PLUS expression as defined in Section 2.6. 


The NEXT statement signals the end of the loop which began with the FOR statement. The NEXT statement is of 
the form: 


NEXT <variable> 


where the variable is the same variable specified in the FOR statement. Together the FOR and NEXT statements 
describe the boundaries of the program loop. When execution encounters the NEXT statement, the computer adds the 
STEP expression value to the variable and checks to see if the variable is still less than or equal to the terminal expression 
value. When the variable exceeds the terminal expression value, control falls through the loop to the statement follow- 
ing the NEXT statement. 


If the STEP expression is omitted from the FOR statement, +1 is the assumed value. Since +1 is a common STEP 
value, that portion of the statement is frequently omitted. 


The expressions within the FOR statement are evaluated once upon initial entry to the loop. The test for completion 
of the loop is made prior to each execution of the loop. (If the test fails initially, the loop is never executed.) 


The control variable can be modified within the loop. When control falls through the loop, the control variable retains 
the last value used within the loop. 


The following is a demonstration of a simple FOR-NEXT loop. The loop is executed 10 times; the value of I is 10 when 
control leaves the loop and +] is the assumed STEP value: 


LISTNH 

1G FOR t-i- tO: 10 
Rae FRINT Is 

30 NEXT I 

AQ) FRINT I 

Re schu 

RUIN NE 


oe ee a ee 


The loop itself is lines 10 through 30. The numbers | through 10 are printed when the loop is executed. After I=10, 
control passes to line 40 which causes 10 to be printed again. If line 10 had been: 


10 FOR Je20-10. 1 -SIer 1 
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the value printed by line 40 would be 1. 


LOO FOR T=2 TQ 44 STEP 2 
\ LET T=44 
S NEAL 


The above loop is only executed once since the value of I=44 has been reached and the termination condition is 
satisfied. 


If, however, the initial value of the variable is greater than the terminal value, the loop is not executed at all. A 
statement of the format: 


100 FOR t=206 1G. 2 StF 2 
cannot be used to begin a loop, although a statement like the following will initialize execution of a loop properly: 
a OQ POr ie 20 tO 2 Sie 2 


For positive STEP values, the loop is executed until incrementing the control variable would cause it to be greater than 
its final value. For negative STEP values, the loop continues until incrementing the control variable would cause it to 
be less than its final value. 


FOR loops can be nested but not overlapped. The depth of nesting depends upon the amount of user storage space 
available (in other words, upon the size of the user program and the amount of memory each user has available). 
Nesting is a programming technique in which one or more loops are completely within another loop. The field of 
one loop (the numbered lines from the FOR statement to the corresponding NEXT statement, inclusive) must not 
cross the field of another loop. Figure 3-1 illustrates correct and incorrect nesting of loops. 


Acceptable Nesting Unacceptable Nesting 
Techniques Techniques 


Two Level Nesting 


FOR I1 = 1 TO 10 FOR I1 = 1 TO 10 
FOR I2 = 1 TO 10 FOR [2 = 1 TO 10 
NEXT [2 NEXT I] 

Be I3=1T0O10 NEXT [2 
NEXT I3 
NEXT I] 


Three Level Nesting 


FOR [1 = 1 TO 10 FOR I1 = 1 TO 10 
FOR 12 = 1 TO 10 FOR [2 = 1 TO 10 
FOR [3 = 1 TO 10 FOR [3 = 1 TO 10 
NEXT I3 NEXT [3 
FOR 14 = 1 TO 10 FOR I4= 1 TO 10 
NEXT 14 NEXT 14 
NEXT [2 NEXT I] 
NEXT [1 NEXT [2 


Figure 3-1 Correct and Incorrect Nesting 
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An example of nested FOR-NEXT loops is shown below: 


Re schy 


LISTNH 

100 FOR AZ=14 TO SZ 

110 FOR BZ=2% TO 10% STEP 2% 
120 FRINT AASEAY 

130 NEXT BAZ 

140 FRINT 

150 NEXT AZ 

32767 ENT 


Re sety 


RUNNH 
bord 2 36 : ee eee eS 


ei 
“. 


Pr 
Ph 
+> 


oe oe 


f3 


190 
‘ee a4 ee re es Raa 29, 
Ss ee 4 4 4 & 4 8 4 10 


_— 
eerie 


uF 
3> 
iii 
ea 
a 


8 ae 


It is possible to exit from a FOR-NEXT loop without the control variable reaching the termination value. A conditional 
or unconditional transfer can be used to leave a loop. Control can only transfer into a loop which had been left earlier 
without being completed, ensuring that termination and STEP values are assigned. 


Both FOR and NEXT statements can appear anywhere in a multiple statement line. For example: 


LISTNH 
LOO FOR: L221. LO eter O\ NEXT 1 - NPR IN eet 


Re acy 


RUNNH 
= 6 


Reaecdy 


Neither the FOR nor NEXT statement can be executed conditionally in an IF statement. The following statements 
are incorrect: 


79O if. <>.-.6 THEN ANERT. 2 
BOG IF I=J THEN FOR I=1 TO J 
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3.6.2 Subscripted Variables and the DIM Statement 

In addition to the simple variables which were described in Chapter 2, BASIC-PLUS allows the use of subscripted 
variables. Subscripted variables provide the programmer with additional computing capabilities for dealing with lists, 
tables, matrices, or any set of related variables. In BASIC-PLUS, variables are allowed one or two subscripts. 


The name of a subscripted variable is any acceptable BASIC-PLUS variable name followed by one or two integer 
expressions in parentheses. For example, a list might be described as A(I) where I goes from 0 to 5 as shown below 
(all matrices are created with a zero element, even if that element is never specified): 


A(0), A(1), A(2), AG), A(4), AGS) 


This allows the programmer to reference each of six elements in the list, which can be considered a |-dimensional 
algebraic matrix as follows: 


eon | son | eon | oon [| 
revo | on | ey | ena, | 7 
a2 | ean | waz | sas) | 7 
sco} san] saa | aaa 7 
ee 


aa 


Figure 3-2 Matrix Structure 


Subscripts used with subscripted variables can be constants or any legal numeric expression. 


It is possible to use the same variable name as both a subscripted and an unsubscripted variable. Both A and A(I) are 
valid variables and can be used in the same program without affecting one another. However, BASIC-PLUS does not 
accept the same variable name as both a singly and a doubly subscripted variable name in the same program. 


NOTE 
There are cases in BASIC-PLUS where a variable name 
without subscripts refers to an entire matrix, and not 
to a simple numeric variable. See the CHANGE state- 
ment, described in Section 5.2, and the MAT statements 
described in Chapter 7. 
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A dimension (DIM) statement is used to define the maximum number of elements in a matrix. (“Matrix” is the general 
term used in this manual to describe all the elements of a subscripted variable.) The DIM statement is of the form: 


DIM <variable (n)>, <variable (n,m)>,... 
Where the variables specified are indicated with their maximum subscript value(s). 


For example: 


110 NIM X€S)e Y¥C4r22)2 ACIOV10) 
L20 NIM T4¢100) 


Only non-negative integer constants can be used in DIM statements to define the size of a matrix. Any number of 
matrices can be defined in a single DIM statement as long as their representations are separated by commas. 


If a subscripted variable is used without appearing in a DIM statement, it is assumed to be dimensioned to length 10 in 
each dimension (that is, having 11 elements in each dimension, 0 through 10). However, all matrices should be 


correctly dimensioned in a program. DIM statements are usually grouped together among the first lines of a program. 


The first element of every matrix is automatically assumed to have a subscript of 0. Dimensioning A(6, 10) sets up 
room for a matrix with 7 rows and 11 columns. This zero element is illustrated in the following program: 


LISTNH 


10 REM - MATRIX CHECK FROGRAM 
fs DIM AC&r19) 
30 FOR I=0 TO 6 
AQ LET A CIsOQ)=7] 
iQ) FOR J=O TO 10 
59 LET ACOs JJ 
7G FRINY ACI» J) ¢ 
\ NEXT 3S 
\ PRINT 
\ NEXT I 
S2ror EN 
Reacdy 
RUNNH 
Oo) 2 SS So Se See 
i 8 = f.5 SO eS ee 
2 Be 2). BO SO 
a 6 > 2 Se OO Oe 
AO Ee ho a Be Oe 
Se he Se ee 
fh = fo) of 6. ee SO 
Reads 


Notice that a matrix element, like a simple variable, has a value of 0 until it is assigned a value. 
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To conserve memory, the user may use the zero-subscripted elements set up within the matrix. For example, DIM 
A(5, 9) generates a 6 X 10 matrix that can be referenced beginning with the A(O, 0) element. 


The size and number of matrices which can be defined depend upon the amount of user storage space available. 
Additional information on matrices can be found in Chapter 7. 


A DIM statement can be placed anywhere in a multiple statement line and anywhere in the program. It need not appear 
prior to the first reference to an array that it defines. DIM statements are usually placed at or near the beginning of a 
program, however, to make them easy to locate should changes be indicated. 


3.7 MATHEMATICAL FUNCTIONS 

Within the course of a user’s programming experience, he encounters many cases where relatively common mathematical 
operations are performed. The results of these common operations can often be found in volumes of mathematical 
tables; i.e., sine, cosine, square root, log, etc. Since it is this sort of operation that computers perform with speed and 
accuracy, such operations are built into BASIC-PLUS. The user need never consult tables to obtain the value of the 

sine of 23 degrees or the natural log of 144. When such values are to be used in an expression, intrinsic functions, such 
as: 


SIN (23.*PI/180.) 
LOG (144.) 


are substituted. 


The various mathematical functions available in BASIC-PLUS are detailed in Table 3-1. 


Table 3-1 
Mathematical Functions 


Function 
Code Meaning 
ABS(X) Returns the absolute value of X 
SGN(X) Returns the sign function of X, a value of | preceded by the sign of X, SGN(0)=0 
INT(X) Returns the greatest integer which is less than or equal to X, (INT(-.5)=- 1) 
FIX(X) Returns the truncated value of X, SGN(X)*INT(ABS(X)), (FIX(-.5 )=0) 
COS(X) Returns the cosine of X (X in radians) 
SIN(X) Returns the sine of X (X in radians) 
TAN(X) Returns the tangent of X (X in radians) 
ATN(X) Returns the arctangent (in radians) of X 
SQR(X) Returns the square root of X 
EXP(X) Returns the value of e X, where e=2.71828... 
LOG(X) Returns the natural logarithm of X, log.X 
LOG10(X) Returns the common logarithm of X, log} qX 
PI Has a constant value of 3.1415927 
RND(X) Returns a random number between 0 and 1. Unless the RANDOMIZE statement 
or is encountered in the RND program prior to encountering the RND function, the 
RND same sequence of random numbers is generated each time a program is run. The 


value of X is ignored, and can be omitted. 


3-21 


Elementary BASIC-PLUS Statements 


Most of these functions are self-explanatory. Those which are not are explained in the following sections. 


3.7.1 Sign Function, SGN(X) 


The sign function returns a value of +1 if X is a positive value, 0 if X is 0, and -1 if X is negative. For example: 
SGN(3.42) = 1, SGN(-42) =-1, and SGN(23-23) = 0. 


LISTNH 
19 REM ~ SGN FUNCTION DEMO 
LOO READ Av 
\ PRINT “’A=’sAv “R=°3R 
L190 FRINT ‘“SGNCA)=’sSGNCA)» “SGNCBR)="’ SGNCER) 
L206 FRINT “SGNCINTCA))=’sSGNCINTCA)D) 
LOOO DATA ~7 e329 0444 
S276? ENT 
Ready 
RUNNH 
ham Ze 32 R= .44 
SGNCAI=~1 SGNCR)= 


SGN CINT CA) =<] 

Ready 
3.7.2 Integer Function, INT(X) 
The integer function returns the value of the greatest integer not greater than X. For example, INT(34.67) = 34. INT 
can be used to round numbers to the nearest integer by asking for INT(X+.5). For example, INT(34.67+.5) = 35. 
INT can also be used to round to any given decimal place, by asking for 


INT(X*10. D%+.5)/10. D% 


Where D is the number of decimal places desired, as in the following program: 


LISTNH 
10 | TEMONSTRATION OF INTEGER CINT) FUNCTION 

\! INT DOES NOT ROUND TO NEAREST 

\! INTEGER» BUT DROFS THE FRACTION FART 
100 INFUT “NUMBER TO BE FROCESSED BY INT FUNCTION’ $A 
110 INFUT “NUMBER OF DECIMAL PLACES FOR ROUNDING’ of 
120 FRINT “TRUNCATED INTEGER=%s INTCA) 
130 PRINT “ROUNDED INTEGER=% sINTCAt.S) 
140 PRINT “ROUNDED TO ‘sts “FPLACES=% 5 

INT CAK1O°U+. 59701 0°R) 

130 PRINT 
140 FRINT “ENTER ANOTHER NUMBER: TYFE A ZERO TO STOF --~’ 
170 INFUT & 
1890 IF Az> O GO TO 110 


32767 END 
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RUNNH 

NUMBER TO BE FROCESSED BY INT FUNCTION? 23.67 
NUMBER OF DECIMAL FLACES FOR ROUNDING? 1 
TRUNCATED INTEGER= 23 

ROUNDED INTEGER= 24 

ROUNDED TO 1 FLACES= 23.7 


ENTER ANOTHER NUMBERs TYPE A ZERO TO STOF ~-- 
P 456.50505 

NUMBER OF DECIMAL FLACES FOR ROUNDING? 2 
TRUNCATED INTEGER= 456 

ROUNDED INTEGER= 437 

ROUNKED TO 2 PLACES= 456.51 


ENTER ANOTHER NUMBER» TYPE A ZERO TO STOP -- 
? 0 


Ready 


For negative numbers, the largest integer contained in the number is a negative number with the same or a larger 
absolute value. For example: INT(-23) = ~-23, but INT(- 14.39) =-15. 


3.7.3 Random Number Function, RND(X) 

The random number function produces a random number between 0 and 1. The numbers are reproducible in the same 
order for later checking of a program. The argument X in the RND(X) function call can be any number, or simply 
omitted as that value is ignored. 


LISTNH 

10 REM -~- RANTIIOM NUMBER DEMONSTRATION 

20 INFUT "HOW MANY RANDOM NUMBERS * 3 N 

30 FOR I=1 TO N 

40 FRINT RNIty 

JO NEXT I 

32767 ENT 

Reachy 

RUNNH 

HOW MANY RANDOM NUMBERS? 13 
+2 QO4935 2229581 0333074 sboeeii 0795602 
‘for Le + 7418354 ~397713 709388 267811 
°682372 ©P91239 «806084 

Ready 
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In order to obtain random digits from 0 to 9, change line 40 to read: 
AQ PRINT INTCLOXRND) » 


and tell BASIC-PLUS to run the program again. This time the results are: 


RUNNH 

HOW MANY RANDOM NUMBERS? 13 
2 2 os 1 9 
7 Z 3 7 & 
& > g 

Reactky 


It is possible to generate random numbers over any range. In general, if the range (A, B) is desired, use: 
(B-A)*RND(X)+A or the equivalent (B-A)*RND+A 
to produce a random number in the range A<n<B. 


3.7.4 RANDOMIZE Statement 
The RANDOMIZE statement is written as follows: 


RANDOMIZE 
or, alternatively: 
RANDOM 


If the random number generator is to calculate different random numbers every time a program is run, the RANDOMIZE 
statement is used. RANDOMIZE is placed before the first use of random numbers (the RND function) in the program. 
When executed, RANDOMIZE causes the RND function to choose a random starting value, so that the same program 
run twice gives different results. For this reason, it is a good practice to debug a program completely before inserting 

the RANDOMIZE statement. 


To demonstrate the effect of the RANDOMIZE statement on two runs of the same program, the RANDOMIZE state- 
ment is included as statement 15 in the following program: 


LISTNH 

10 REM ~ RANDOM NUMBER DEMONSTRATION 
15 RANIOMIZE 

20 INFUT "HOW MANY RANDOM NUMBERS“ 5N 
30 FOR I=1 TO N 

40 PRINT RNIs 

JO NEAT ST 


32767 END 


Reads 
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RUNNH 

HOW MANY RANIIOM NUMBERS? 35 
~9415S9 249281 °621653 «486387 0 32545 
+ J65214 *>468236 > 740494 228836 «708373 
eave eis »774316 -718683 + J4 3249 eF9135 
-O358857 +430996 ~562536E-1 *458616 6245325 
+ 344403 *858497 ssLadeue™1 ©381639 27 6619E-1 
<Joaiene + 338373 © 649245 -850108 »257448 
©893713 eAS2Z437E-1 +228047 «961087 °714104 

Ready 

RUNNH 

HOW MANY RANDIDIOM NUMBERS? 12 
* 448782 0692627 116732 *+466741 °> 749863 
°298S1 °422888E-1 7367144 9022262 292799E~1 
iVFiases + 388409 

Ready 


The output from each run is different. 


3.7.5 User-Defined Functions 

In some programs it may be necessary to execute the same sequence of statements or mathematical formulas in several 
different places. BASIC-PLUS allows the programmer to define his own functions and call these functions in the same 
way he would call the standard system functions, such as RND, SQR, or COS. 


These user-defined functions consist of a function name, the first two letters of which are FN followed by any valid 
variable name. For example: 


FNA 
FNAI1 


The function can be defined anywhere in the program, even before its first use. The defining or DEF statement is 
formed as follows: 


DEF FN a (arguments) = <expression (arguments)> 
where a is any legal variable name. The arguments may consist of zero to five dummy variables. The expression, 
however, need not contain all the arguments and may contain other program variables not among the arguments. For 
example: 

100 QEF FNACS) = $°2 
causes a later statement: 


L190 LET RK =FNAC4) +1 


to be evaluated as R=17. As another example: 


a iQ DEF FNECAsR) = AtX™?2 
2OQ Y=FNEC14.49R3) 
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causes the function to be evaluated with the current value of the variable X within the program. In this case the dummy 
argument B (which becomes the actual argument R3 in the function call) is unused. 


The following two programs each produce the same output. 


Program 1: 
LISTNH 
10 ! YEMO OF FUNCTION DEFINITION 
LOO NEF FNSCA)=A™A 
110 FOR I=1 TO 9$ 
\ PRINT Is FNSCT) 
\ NEXT I 
32767 END 
Ready 
Program 2: 
LISTNH 
10 1 TEMO OF FUNCTION DEFINITION 
100 NEF FNS¢X)=X°X 
110 FOR I=1 TO 3 
\ PRINT Is FNSCT) 
\ONEAT o£ 


32767 ENT 
Ready 


The output is the following: 


RUNNH 
1 1 
~ 4 
7 ar 
4 296 
3 Siae 
Ready 


DEF statement arguments are formal variables. When the defined function is later invoked, the variables are keyed by 
position in the argument list, not by the characters used to form the arguments. The function itself can be defined in 
the DEF statement in terms of numbers, variables, other functions, or mathematical expressions. For example: 


LISTNH 

100 NEF FNACX) = X°24+3kKX+4 

(200 NEF FNECX) = FNACX)/2 + FNACX) 
300 NEF FNCCX) = SQRCX+4) + I 


i 
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The statement in which the user-defined function appears can have that function combined with numbers, variables, 
other functions, or mathematical expressions. For example: 


AQ LET Ro = FNACX+Y+Z)KN/CY°2+D) 

A user-defined function can be a function of zero to five variables, as shown below: 
oo DEF FNL (CXs¥sZ) = SQRCX 2 + YC! + Z2°2) 

A later statement in a program containing the above user-defined function might look like the following: 
Ja LET B = FNL CDtyly RR) 

where D, L, and R have some values in the program. 


The number of arguments with which a user-defined function is called must agree with the number of arguments with 
which it is defined. For example: 


100 NEF FNACX) = Xx*S 
110 PRINT FNAC3s2) 


will cause an error message: 
TArsgumemts don’t match at line 110 


In a DEF statement or function reference, where a function has zero arguments, the function name can be written with 
or without parentheses. For example: 


Reacty 

OLD C3rPS32 

Reach 

LISTNH 

10 QEF FNA=X"2 

<0 INFUT ‘“TYFE A NUMBER’ 3X 


30 PRINT FNAs FNAC) 
32767 ENT 


RUNNH 
TYPE A NUMBER? 3-65 
13.3225 13.3225 


Ready 


When calling a user-defined function, the parenthesized arguments can be any legal expressions. The value of each 
expression is substituted for the corresponding function variable. For example: 
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LISTNH 
10 NEF FNZCXIHEXT2 
a ©) LET Ar2 


\PRINT FNZC2+A) 
32/67 EN 


Reacts 


RUNNH 


14 
Rt es cfs 


If the same function name is defined more than once, an error message is printed. 


LOO DEF FNXCX3=xX°2 
119 NEP FNX CX) = x74 


Fi[llesgal FN redefinition at line 110 
Keech 


The function variable need not appear in the function expression as shown below: 


_LISTNH 
100 i} FUNCTION VARTABLE NOT IN FUNCTION EXFRESSION 
110 DEF FNACX?) = 4xA +2 
L20 FOR A = O TQ 3 
130 LET KR = FNACIO) + 1 
\ PRINT K 
\ NEXT A 
ge fG7 ENT 
Re ach 
RUNNE 
3 
? 
+i 
13 
Re acty 


The program in Figure 3-3 contains examples of a multi-variable DEF statement in lines 30, 50, and 70. 


3.8 SUBROUTINES 

When a particular mathematical expression is evaluated several times throughout a program, the DEF statement 
enables the user to write that expression only once. The technique of looping allows the program to do a sequence of 
instructions a specified number of times. If the program should require that a sequence of instructions be executed 
several times in the course of the program, this is also possible. 
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LISTNH 
10 REM ~~ MODULUS ARITHMETIC FROGRAM 
THIS PROGRAM CREATES ADQITION ANT 
MULTIPLICATION TABLES FOR A SPECIFIED 
MODULUS Me 
= Q REM ~~ FUNCTION TO FIND xX MOD M 
30 NEF FNM(X»M)=X-MKINTOX/M) 
| 
40 REM ~~ FUNCTION TO FING AtR MOD M 
wi NEF FNACAs Be» M2=FNM CATR» M) 
&Q REM -~ FUNCTION TO FIND AXE MOD 
79 DEF FNECA»sByM)=FNMCAXKE 9M) 
100 FRINT \ FRINT “AQ00TTIOQN ANDO MULTIFLICATION TABLES MON M’ 
\ INFUT “WHAT MODULUS “9M 
\ PRINT \N FRINT “ADDITION TABLES MOD’ $M 
\ GOSUR 800 
110 FOR T=O TO M-1 
120 PRIN is" *9 
\ FOR. J=0 10 M-1 
\ PRINT FNACT sy J9M) > 
\ NEAT J 
\ FRINT 
ee. SS ee 
\ PRINT \ PRINT 
OQ PRINT “MULTIPLICATION TABLES MOD’ 5M 
\ GOSUBR 800 
21 O° FOR I=0 TO M~1 
PRIN 17% *3 
\FOR J=0O TO M<-1 
\NPRINT FNECD ste M) » 
\NEAT J 
\FPRINT 
\NEXT I 
ea GOTO 32767 
BOO REM -~ THIS SUBROUTINE FRINTS THE HEADINGS FOR EACH TABLE 
S10 PRINT 
\ FRINT TARC4) 3 
B20 FOR T=0 TO M~1 
\NPRINT Is 
\NEAT I 
\PRINT 
830 FOR T=1 TO 3xMt4 
\ PRINS 2-9 
\ NEXT I 


\ FRINT 
\ RETURN 
32767 EN 


Fi ge a chy 


Figure 3-3 Modulus Arithmetic 
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ADDITION ANT 
WHAT MODULUS? 7? 


MUL TIFLICATION TABLES 


ANNITION TABLES MOD 7 


PSOe COS SHED FOOD ODES SOSH FOSS SETE FOES SEES SESE GHEE SOHT SEES BO0F SESS SOO SEES SEES COOE BEES SEEE COe8 S48 ween 


on Clb Whe © 


MULTIPLICATION TABLES MOD 


SOS COSS BOOS CHEE FEOF SHOE SESS FEES THES FHOT SEES SOHT CESE FO88 COOE OFFS COEF SOEE S046 SOE8 Soon SESE SOOE SEEt SeOt 


oo Ch > Whe 
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Figure 3-3 (Cont.) Modulus Arithmetic 
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A subroutine is a section of code performing some operation required at more than one point in the program. Some- 
times a complicated I/O operation for a volume of data, a mathematical evaluation which is too complex for a user- 
defined function, or any number of other processes may be best performed in a subroutine. 


More than one subroutine can be used in a single program, in which case they can be placed one after another at the end 
of the program (in line number sequence). A useful practice is to assign distinctive line numbers to subroutines; for 
example, if the main program uses line numbers up to 199, use 200 and 300 as the first numbers of two subroutines. 
Consider the following example: 


LISTNH 
10 REM ~~ THIS FROGRAM ILLUSTRATES GOSUB ANT RETURN 
oO NEF FNACX)=ARSCINT(X)) 
30 FRINT “THIS SUBROUTINE FINKS QUADRATIC SOLUTIONS’ 
AQ INFUT “ENTER THREE COEFFICIENTS ’$ AvyBsl 
\ FRINT 
\ PRINT “SOLUTIONS FOR COEFFICIENTS ENTERED ARE “ 
\ FRINT “SHOWN FIRST» THEN SOLUTIONS FOR’ 
\ PRINT ‘ABSOLUTE VALUE COEFFICIENTS. “ 
wh 6) GOSUB SOO 
50 LET A=FNACA) 
\ R=FNACE) 
\ C=FNACC) 
70 PRINT 
\NPRINT “WITH ALL COEFFICIENTS CONVERTED TO ABSOLUTE?‘ 
80 GOSUR 300 
20 PRINT “TYPE "MORE" IF YOU WANT TO CONTINUE“ 
100 INFUT AS 
\ IF At = “MORE" THEN 40 
L190 GO TO 32767 
3OO REM -~ THIS SUBROUTINE FRINTS OUT SOLUTIONS OF THE 
EQUATION AXX”°2+BKX+C=0 
JLO PRINT 
NPRINT “THE EQUATION IS ’#A#‘°XX"2 + ‘SBR’ KX + °SC3° = 
wae O LET D=BKER~4XAXKC 
\ IF Q8>0 THEN 600 
330 PRINT “ONE SOLUTION? X=’s-B/(2kA) 
\ RETURN 
4500 IF 0&0 THEN 700 
600 PRINT “TWO SOLUTIONS? X=(7%3 
S10 PRINT (-B+SQR(D))/(2kA)5%) AND (4°53 (-B-SQR(D)/(C2kA) G7)? 
\ RETURN 
700 PRINT “IMAGINARY SOLUTION? X=(7%3 
710 PRINT -B/(2kA) 5 +s SQRC-DD/C2keA) 5 4 T) ¢ 
720 PRINT: <f ANT (€%% 
730 PRINT ~B/(2KA)5 °° sSQRC-D/C2kKA) #71)’ 
\ RETURN 


32767 ENT 
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RUNNH 
THIS SUBROUTINE FINUS QUADRATIC SOLUTIONS 
ENTER. THREE -CDEFFICIENIS? -1s-Se-6 


SOLUTIONS FOR COEFFICIENTS ENTERED ARE 
SHOWN FIRST» THEN SOLUTIONS FOR 
ARSOLUTE VALUE COEFFICIENTS. 


THE Stig ION 75-1. £xX-2 4+ -3° 2K 4+ 6 = 
TWO SOLUTIONS? X=¢€ 6 2 AND (-1 >) 


WITH ALL COEFFICIENTS CONVERTER TO ABSOLUTE? 


THE -EOUATION [61 Shot 9 ee 62S 0 
TWO SOLUTIONS? X=(-2 ) AND (-3 3 

TYFE "MORE*® IF YOU WANT TO CONTINUE 

* MORE 

ENTER SKE E CORFEICIENI SG? 2x ae~2 

SOLUTTONS FOR COEFFICIENTS ENTERED ARE 
SHOWN FIRSTs THEN SOLUTIONS FOR 

ABSOLUTE VALUE COEFFICIENTS. 


THE--EGUATION 35. 2 2x°2>4  S228% + -2 =. 9 
TWO SOLUTIONS: X=€ «5 ) ANDI (-2 ) 


WITH ALL COEFFICIENTS CONVERTED TO ABSOLUTE? 
THE EAUATION JIS 2. 4X" 2 ob 45 RK HE CS ce GD 
IMAGINARY SOLUTION? X=¢€-.75 + .661438 I) 

ANT ¢-.73 - .661438 J) 
TYFE "MORE" IF YOU WANT TO CONTINUE 
? NO 
Re schy 


Lines 500 through 730 constitute the subroutine. The subroutine is executed from line 50 and again from line 80. 


3.8.1 GOSUB Statement 
Subroutines usually are placed physically at the end of a program before DATA statements, if any, and always before 
the END statement. The program begins execution and continues until it encounters a GOSUB statement of the form: 


GOSUB <line number> 


where the line number following the word GOSUB is the first line number of the subroutine. Control then transfers to 
that line in the subroutine. For example: 


wi) GOSUR 200 


Control is transferred to line 200 in the user program. The first line in the subroutine can be a remark or any executabl: 
Statement. 
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3.8.2 RETURN Statement 
Having reached the line containing a GOSUB statement, control transfers to the line indicated after GOSUB; the sub- 
routine is processed until the computer encounters a RETURN statement of the form: 


RETURN 


which causes control to return to the statement following the original GOSUB statement. Subroutine exit is always 
through a RETURN statement. 


Before transferring to the subroutine, BASIC-PLUS internally records the next sequential statement to be processed 
after the GOSUB statement; the RETURN statement is a signal to transfer control to this statement. In this way, no 
matter how many subroutines or how many times they are called, BASIC-PLUS always knows where to go next. 


3.8.3 Nesting Subroutines 

Subroutines can be nested; that is, one subroutine can call another subroutine. If the execution of a subroutine 
encounters a RETURN statement, it returns control to the line following the GOSUB which called that subroutine. 
Therefore, a subroutine can call a subroutine, including itself. Subroutines can be entered at any point and can have 
more than one RETURN statement. It is possible to transfer to the beginning or to any part of a subroutine; multiple 
entry points and returns make a subroutine more versatile. 


The maximum level of GOSUB nesting is dependent on the size of the user program and the amount of memory avail 
able at the installation. Exceeding this limit causes the message: 


?MAXIMUM MEMORY EXCEEDED AT LINE line number 
3.9 STOP AND END STATEMENTS 
The STOP and END statements are used to terminate program execution. The END statement is the last statement 
in a BASIC-PLUS program. The STOP statement can occur several times throughout a single program with condi- 
tional jumps determining the actual end of the program. The END statement is of the form: 

END 
The line number of the END statement should be the largest line number in the program, since any lines with line 
numbers greater than that of the END statement are not retrieved by a subsequent OLD command after the program 


is saved. The user can habitually number each END statement 32767 to avoid this problem. 


A program will execute without an END statement. However if a program retrieved by an OLD command includes no 
END statement, RSTS/E prints the following informative message: 


FTEnd of file on device 
The STOP statement is of the form: 

line number STOP 
and causes: 


STOP AT LINE line number 
READY 


to be printed when executed. A CONTINUE command entered at this point resumes execution at the statement 
following STOP. 
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Execution of aSTOP or END statement causes the message: 
Ready 
to be printed by the teleprinter. This signals that the execution of a program has been terminated or completed, and 


BASIC-PLUS is able to accept further input. The execution of an END statement also closes all files in a BASIC- 
PLUS program. 
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BASIC-PLUS ADVANCED FEATURES 


Part II describes certain features of BASIC-PLUS that give the language flexibility for a greater variety of applica- 
tions. Additional capabilities of the statements previously described are included, along with new statements, 
character string manipulation, string arithmetic (an optional feature), integer mode variables and arithmetic, and 
intrinsic matrix functions (an optional feature). Also described in the immediate mode of operation which causes 
BASIC-PLUS to treat single statements as commands. 


In general, the techniques presented here allow the user to write programs which conserve memory space and reduce 
execution time. With the ability to manipulate character strings, the user can write sophisticated programs to handle 
a wide range of data. Also, the ability to perform arithmetic with numeric string data enables the user to obtain 
greater precision than is possible with floating point and integer operands. 


The matrix functions allow the user to perform matrix I/O and the matrix operations of addition, subtraction, 
multiplication, inversion and transposition. 


Nonna 
a 


CHAPTER 4 
IMMEDIATE MODE OPERATIONS 


4.1 USE OF IMMEDIATE MODE FOR STATEMENT EXECUTION 

It is not necessary to write a complete program to use BASIC-PLUS. Many BASIC-PLUS statements are executable 
as on-line commands, i.e., executed immediately by the BASIC-PLUS processor. This facility provides a powerful 
on-line desk calculator. It allows the user to check and change variables of the current program, or perform calcula- 
tions independent of the current program. Thus it is a helpful tool for program design and debugging. 


BASIC-PLUS distinguishes between lines entered for later execution and those entered for immediate execution 
solely on the presence (or absence) of a line number. Statements which begin with line numbers are stored; state- 
ments without line numbers are compiled and executed immediately upon being entered to the system. Thus the 
line: 

19 FRINT “THIS IS AN EXECUTABLE BASIC-FLUS FROGRAM’ 
produces no action at the terminal upon entry, while the statement: 

PRINT “THIS IS AN IMMEDIATE MODE STATEMENT’ 
when entered causes the following immediate output: 

THIS IS AN IMMEDIATE MONE STATEMENT 

Ready 
The READY message is then printed to indicate the system readiness for further input. 
Although only one statement at a time can be executed in immediate mode, statements typed in immediate mode 


can reference variable values established either by the running of the current program or by other immediate mode 
statements. For example: 


A= 3 
React 
Ban 4 
Ready 


PRINT ATNCA/B) 
+643501 


PRINT SQR(A™2 + BD) 


wd 


Rescy 
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4.2 PROGRAM DEBUGGING 

Immediate mode operation is especially useful in two areas: program debugging and the performance of simple 
calculations in situations which do not occur with sufficient frequency or with sufficient complications to justify 
writing a program. 


In order to facilitate debugging a program, the user can place STOP statements liberally throughout the program, 
Each STOP statement causes the program to halt, printing the line number at which the STOP occurred. The user 
then can examine various data values, perhaps change them in immediate mode, and then give the CONT command 
to continue program execution. However, a syntax error in immediate mode or one of several other conditions 
could prevent continuation of program execution with the CONT command. 


When using immediate mode, nearly all the standard statements can be used to generate or print results. 


The user can also halt program execution at any time by typing CTRL/C. Immediate mode can then be used to 
examine and/or change data values. Typing the CONT command resumes program execution. 


However, if the CONT command is entered and execution cannot be resumed, the following message is printed. 
?PCan’t CONTinue 
Ready 

When a program is interrupted by typing the CTRL/C combination, the integer variable LINE contains the line 


number of the statement being executed when the interrupt occurred. The PRINT command is used to display the 
contents of LINE. 


eS 
Re schy 


FRINT LINE 
300 


Re acy 


4.3 MULTIPLE STATEMENTS PER LINE 

Multiple statements cannot be used on a single line in immediate mode. For example: 
A=1 \ FRINT A 
Plllegal in immediate mode 


The use of the FOR modifier (and all other modifiers described in Section 8.7) is allowed. Thus a table of square 
roots can be produced as follows: 
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PRINT. lx SQR(1) FOR: Ef = 1 70-10 
1 1 

1.41421 

Le 73205 


a 


dee 


ee 3607 
2+ 44949 
22 G45735 
2oB82843 
“3 

0 3+¢16228 


m~ CON & CHD OPS 


Ready 


4.4 RESTRICTIONS ON IMMEDIATE MODE 
Certain commands make no logical sense when used in immediate mode. Commands in this category include: 


DEF 
FNEND 
DIM 
DATA 
FOR 
NEXT 


When any of these is given, the message ILLEGAL IN IMMEDIATE MODE is printed. 
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CHAPTER 5 
CHARACTER STRINGS 


5.1 CHARACTER STRINGS 

The previous chapters describe the manipulation of numerical information; however, BASIC-PLUS also processes 
information in the form of character strings. A string, in this context, is a sequence of characters treated as a unit. 
A string can be composed of any combination of ASCII characters. 


In Chapter 3 the INPUT and PRINT statements were shown printing messages along with the input and output of 
numeric values (see lines 10 and 15 above). These messages consist of character string constants (just as 4 is a numeric 
constant). In a similar way, there are character string variables and functions. 


5.1.1 String Constants 
Just as numbers can be used as constants or referenced by variable names, BASIC-PLUS allows for character string 
constants. Character string constants are delimited by either single or double quotes. For example: 


100 Let 4S = Fei Le4" 
2O0 BiG = ‘CAN’ 
300 if As —= TYES”* GO 70-200 


where ““FILE4’, ‘CAN’ and ““YES” are character string constants. 


5.1.2 Character String Variables 

Variable names can be introduced for simple strings and for both lists and matrices composed of strings (which is to say 
1- and 2-dimensional string matrices). Any legal name followed by a dollar sign ($) character is a legal name for a string 
variable. (The rules for forming legal variable names are described in Section 2.5.2.) For example: 


A$ 
C7$ 
NAME.OF.CUSTOMER$ (EXTEND mode only) 


are simple string variables. Any list or matrix variable name followed by the $ character denotes the string form of that 
variable. For example: 


VS(N%) M25(N%) 
C$(M%,N%) G1$(M%,N%) 


(where M and N indicate the position of that element of the matrix within the whole) are list and matrix string variables. 


The same name in combination with various prefixes and suffixes can appear in the same program, and generate mutually 
independent variables. For example, the name A refers to a floating-point variable A. The name A can be used as follows: 
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A floating point variable A 

A% integer variable A% 

A$ string variable A$ 

A(d) floating point array A with dimension specification d 
A%(d) integer array A% with dimension specification d 
AS$(d) string array A$ with dimension specification d 

FNA floating point function FNA 


FNA% integer function FNA% 
FNA$ string function FNA$ 


Thus any name can be used to reference up to nine distinct data entities. In the case of an array, there can be only one 
dimension specification in the program for each A(d), A%(d), or A$(d). For example, the following combination is legal. 


10 DIM AZCLOG)y AC200>) 
2 Q AAZIOA 

ae AACLSI=1LO0“4 

AQ AZCAK)=2004 


It will place a value of 50 in the integer variable A%, 100 in element 25 of array A%, and 200 in element 50 of array A%. 
Array A is not affected. On the other hand, the following DIM statement is illegal. 


et D OIM ASCSOI » AFC1LOr4) 
?Redimensioned array at line 250 


because it attempts to use the same string array name to identify two arrays. There would be no logical conflict if one 
instance of A$ were A or A%. 


Just as numeric variables are automatically initialized to 0 when a program is run, string variables are initialized to a null 
string containing no characters (the character string constant “”’). 


5.1.3 Subscripted String Variables 
String lists and matrices are defined with the DIM statement, as are numerical lists and matrices. For example: 


100 LIM Sils(S) 


indicates the S1$ is a string matrix with six elements, $1$(0) through S1$(5), which can be separately accessed. If a 
DIM statement is not used, a subscripted string variable is assumed to have a dimension of 10 (11 elements including 
the zero element) in each direction. Note that the dimension of a string matrix specifies the number of strings and not 
the number of characters in any one string. For example, if the first statements in a program are: 


LO20 EUR: Tel TO. 7 
ee ee ees SS ees a oe © 
\REAT 


a list B$(n) is created having 11 accessible elements, B$(0) through B$(10). The elements B$(1) through B$(7) are set 
equal to ““PDP-11”’ and the others would be null strings (have no characters), as shown below. 
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LiISTNH 
1050 FOR [=1 TQ 7 
\. LET Bé¢ T= "PoP 74 
\ NEXT 4 
1060 FOR H=O TO 10 
\ PRINT He B&CHD 
\ NEXT H 
Sel GP ENG 
Re acty 
RUNNH 
0 
1. PoP 1 1 
2 POF -11 
3 PP -1 1 
‘ POP-11 
pa FOF 11 
& ep te 
7 PiP~11 
£3 
} 
10 
Re acs 


As a general rule, all lists should be dimensioned to the maximum size referenced in the program. 


5.1.4 String Size 
A character string can contain any number of characters limited only by the amount of memory available. However, the 
LINE FEED key cannot be used to type a string on two or more terminal lines. To create a string longer than a terminal 


line, it is necessary to use string operations (concatenation, for instance) described later. Since memory is limited, 
strings can also be saved in files on the system disk. 


5.1.5 Relational Operations 
When applied to string operands, the relational operators indicate alphabetic sequence. For example: 


wl IF A$CT) <= A$CT4+1) GOTO 100 
When line 55 is executed the following occurs: A$(I) and A$(I+1) are compared; if A$) occurs earlier in alphabetical 


order than A$I+1), execution continues at line 100. Table 5-1 contains a list of the relational operators and their string 
interpretations. 


In any string comparison (except ==), trailing spaces are ignored. The string “YES” is equivalent to “YES ”’. 


When two strings of unequal length are compared, the shorter string (of length n) is compared with the first n characters 
of the longer string. If this comparison is not equal, that inequality is the result of the original comparison. If the first 

n characters of the strings are the same, the strings are equal if the excess characters in the longer string are all blanks. 
Otherwise, the longer string is greater than the shorter string. 


A null string (of length zero) is less than any string of length greater than zero unless that string consists of all blanks in 
which case the two strings are equivalent. 
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Table 5-1 
Relational Operators Used with String Variables 


A$ = B$ The strings A$ and B$ are equivalent, except for possible trailing spaces. 
A$ < BS 
A$ <= B$ 
A$ > B$ 
A$ >= B$ 
A$ <> B$ 
A$ == B$ 


The string A$ occurs before B$ in collating sequence. 


The string A$ is equivalent to or occurs before BS in collating sequence. 


The string A$ occurs after B$ in collating sequence. 


The string A$ is equivalent to or occurs after B$ in collating sequence. 


The strings A$ and B$ are not equivalent. 


The strings A$ and B$ are identical (i.e., same length, composed of the same 
characters in the same order). 


5.2 ASCIT STRING CONVERSIONS, CHANGE STATEMENT 

Individual characters in a string can be referenced through use of the CHANGE statement. The CHANGE statement pe - 
mits the user program to transform a character string into a list of numeric values or a list of numeric values into a 
character string. Each character in a string can be converted to its ASCII equivalent or vice versa. 


Appendix D, Section D.2 describes the relationship between the ASCII characters and their corresponding decimal val- 
ues. Note that several ASCII characters have no graphic equivalent; that is, they cause no character to be printed. 


As an illustration, consider the following: 


LISTNH 

1000 REM ~~ STRING/ASCII CHANGE DEMO 
1010 IM X¢3) 

1020 LET A$ = "CAT" 

1030 CHANGE At TO x 

1040 X=X(O}4FX(3) 


N PRINT “X=’sXs’THE ARRAY X IS 73 
RCOVFXCLIFXC BE XCS) 

1050 'IN A CHANGE STATEMENT THE NUMERIC MATRIX 
PIS REFERENCED WITHOUT SUBSCRIFTS. aS THIS 
EXAMPLE SHOWS» HAVING A SINGLE-VALUE VARTABLE 
IWITH THE SAME NAME IN THE FROGRAM CAUSES 
INO AMBIGUITY. 

S27 67 ENI 


Re scy 


RUNNH 
x= O7 THE ARRAY X IS 3 67 65 94 


Me chy 
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X(1) through X(3) take on the ASCII values of the characters in the string variable A$. The first element of X, X(0), 
becomes the number of characters present in A$. 


If more characters are present in the string variable than can be accommodated in the numeric list, the message 
SUBSCRIPT OUT OF RANGE is printed. The first element of the list becomes the number of characters in the entire 


string and is greater than the dimension of the list. 


Notice that line 1010, above, created a 4-element array, X. A DIM statement must be used in this instance; otherwise, 
the system creates a default 121-element array, possibly causing unexpected results. 


Another program which transforms a character string into a list of numeric values is shown below: 


LISTNH 
100 NIM AC65) 
110 READ At 
120 CHANGE A TO A 
130 FOR I=0 TO ACO) 
XN !'ACO) GIVES LENGTH OF STRING 
140 PRINT ACI); 
\ NEXT I 
200 NATTA ABCUEFGHI JIKRLMNOFQRS TUVWXYZ 
352767 ENT 
Ready 
RUNNH 


<o G0. G6. G7 68: 69 70-21 Ji 78 PR TS Tb OFF 78 8 8 = 8 


S2 83 84 83 86 87 88 89 99 
Ready 


Notice that A(0) = 26 


To change numbers into string characters, the CHANGE statement is used as follows: 


LISTNH 
100 REM -- ASCII NUMBER TO STRING CONVERSION DEMO 
110 FOR T=0 TQ & 
\ READ ACT) 
bree. |S Bee 
120 CHANGE A TO At 
\ PRINT AS 


200 DATA 6265966967268 269% 70 
32767 ENII 


Reacty 


RUNNH 
ABCTIE 


Re sci 


This program prints ABCDE because the numbers 65 through 69 are the code numbers for A through E. 
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Before CHANGE is used in the matrix-to-string direction, the programmer must indicate the number of characters in 
the string as the zero element of the matrix. If element 0 has a value of zero, the CHANGE statement generates a 
zero-length string. 


5.3 STRING INPUT 
The READ, DATA and INPUT statements can be used to input string variables to a program. For example: 


10 READ Atty By CoD 
150 DATA L7el4913.49CAT 


causes the following assignments to be made: 


A$ = the character string “17” 

B= 14 

C= 13.4 

reading D as CAT causes the message ILLEGAL NUMBER AT LINE 10 to be printed. 


Quotation marks are necessary around a string item in a DATA statement only when the string contains a comma, or 
when leading, trailing or embedded spaces within the string are significant, or when lower-case letters are to be pre- 
served. Quotes (single or double) are always acceptable around string items, even though not always necessary. For 
example, the items in line 500 in the following program are all acceptable character strings. 


LISTRH 

LOO REAL Atyk$eo Che Tbe bt 

110 FRINT Abts Bes Che Ds ES 

120 FRINT Aty Bey Chee Tbe Es 

mae) NATTA “MR. JONES’s MISS SMITHy “MRS. BROWN" y ‘MISS’ »’ "MR"? 
Setar ENT 

Rae act 

RUNANH 

MR. JONESMISSSMITHMRS. BROWNMISS"MR* 

Mee JONES MISSSMITH MRS. BROWN MISS eMR* 


Re acy 


Although the string MISS SMITH is acceptable without quotes, embedded spaces in the string are discarded. A READ 
statement can appear anywhere in a multiple statement line, but a DATA statement must be the last statement on a 
line. See also the MAT READ statement which reads matrices (either numeric or string), Section 7.2. 


NOTE 
The data pool composed of values from the programmed 
DATA statements is stored internally as an ASCII string 
list. Where a numeric variable is read, the appropriate ASCII 
to numeric conversions are performed. Where a string variable 
is read, the string is used as it appears in the DATA state- 
ment. If the item did not appear in quotes, leading, trailing 
and embedded spaces are ignored. If the item did appear in 
quotes, the string variable is equated to the entire string 
within the quotes. 
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The input statement is used to input character strings exactly as though accepting numeric values. For example: 
LOO INFUT “YOUR NAME’ sN#s “YOUR AGE’ ¢A 


is functionally equivalent to: 


100 FRINT “YOUR NAME? 9 
Lio INFUT N& 

L2o FRINT “YOUR AGE“ s 
130 INFUT A 


5.3.1 Line Input 
Another feature of the INPUT statement when used with character string input is the INPUT LINE statement of the 


form: 
INPUT LINE <string variable> 


For example: 
INPUT LINE Ag 


which causes the program to accept a line of input from the terminal with embedded spaces, punctuation characters, 
or quotes. Any characters are acceptable in a line being input to the program in this manner. The program can then 
treat the line as a whole or in smaller segments as explained in Section 5.5 which describes string functions. 


No text string can be output with the INPUT LINE statement; this facility is only available in the INPUT statement. 
For example: 


10 TNEUT LINE “TEXT? sA¢ 
?Gumtax error at line 106 


Rie a tity 


An INPUT LINE statement reads the entire line as typed by the user, including the line terminating character. The line 
terminator is one of the following: 


1. Carriage return/line feed, generated by typing the RETURN key (appends the ASCII values 13 and 10 to the 
character string); 

2. Line feed, generated by typing the LINE FEED key (appends the ASCII values 10, 13, and 0 to the 
character string); or 

3. ESCAPE, generated by typing the ESCAPE, ALT MODE or PREFIX key, depending upon the terminal 
(appends an ASCII 27 to the character string). 

4. Form feed, generated by typing CTRL/L (appends an ASCII 12 to the character string). 


Upon receipt of an INPUT or INPUT LINE statement, BASIC-PLUS issues a prompt symbol in the form of question 
mark and a space to signal that the next line typed will be treated as input. Depending on the present loading of the 


system, additional prompts may appear while entering long string input. These prompts are not included in the input. 


After 256 characters are entered, the error message, LINE TOO LONG, is printed. When excessive input is entered to 
cause this message, the string variable will have unpredictable contents. For example: 
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LISTNH 

100 FRINT “ENTER LONG STRING’ 
\ INFUT LINE A 
\ FRINT 
\ FRINT A 

32767 ENT 

Reads 

RUNNH 


ENTER LONG STRING 

Poye/0 oe 74" 3 INFOCNQIIKMNHEFFFFEFEFEFFEEEEEF EEE S535 55566666777 788B890L1LL1122 
2S SS44RREFFCOSSWWEERGNNM » og IKKLL 3 3033 3 CODA ARR KKK EEE EEUU TROL BRB 
RERFFFFFRFFRFFFEFFRRRRRRRRR444444495559556? 6666677777 78888889999T TT ITT IuuUU 
UY YYYFFFFFFVVVUVVUBRRERNNNNMMMVYV? VUCCCSSSSAAAAQRASSSSWWWEEININ4 444444444444 
NAA KA hha ES ZRSEGESESFEEEEECOC CE! I! LT HHHHHS66666677777788887? Line + 
oo lons at line 100 


? HH 
NAMA A4ANAAAQAAGALYLLAAZAZAL OOOO ERE REEEHESDEREEECC COE! IIE LHAAAHHE 
Ready 


The GET statement can also be used to input string information from a terminal in the form of I/O records. See 
Section 12.3 for further information. 


5.4 STRING OUTPUT 

When string values are included in a PRINT statement (either alone or in combination with other string and numeric 
values), no leading or trailing spaces are added to the string. Only the actual content of the string is printed, and leading 
or trailing spaces must be included in the string when it is defined. For example: 


LISTNH 
100 REM -- STRING OUTFUT DEMO 
LOO LET X=1,.0 
\ Yu?,. Ol 
\ Age FAs" 
210 PRINT AgsX" Bet ¥ 
ae FRINT “’RONE ’ 
32767 ENT 
Re a&chy 
RUNNH 
A= Jj] EK= 2.01 
NONE 
Fe ee es ch ty 


Semicolons separating character string constants from other list items are optional. For example, in line 210 (above) 
note that the variable Y is not separated from the character string “* B=” by a semicolon. 


Character string output can also contain the string functions described in Section 5.5. 
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5.5 STRING FUNCTIONS 

Besides intrinsic mathematical functions (e.g., SIN, LOG), BASIC-PLUS contains various functions for use with 
character strings. These functions allow the program to perform arithmetic operations with numeric strings, concatenate 
two strings, access part of a string, determine the number of characters in a string, generate a character string cor- 
responding to a given number or vice versa, search for a substring within a larger string, and perform other useful 
operations. (These functions are particularly useful when dealing with whole lines of alphanumeric information input 
by a INPUT LINE statement.) The various functions available are summarized in Table 5-2. 


Table 5-2 
String Functions 


LEFT(A$,N%) Indicates a substring of the string A$ from the first character through the Nth charac- 
ter (the leftmost N characters of the string A$). For example: 


LO A=“ ARCTERPGHIIRLMNOFQRS TUVWXYZ ¢ 
RUNNH 7 


Re a city 

FRINT LEFT CAs 74) 
ARCIEFG 

Rie a chs 


RIGHT(A$,NZ) Indicates a substring of the string A$ from the Nth character through the last charac- 
ter in A$ (the rightmost characters of the string A$ starting with the Nth character). 
For example: 


FRINT RIGHT CA$s 204) 
TUVWXYZ 


Reacdty 


MID(A$,N1%,N2%) Indicates a substring of the string A$ starting with character N1, and N2 characters 
long (the characters between and including the N1 through N1I+N2-1 characters of 
the string A$). For example: 


PRINT MIDCA$y 15% 95%) 
OF ARS 


Re acy 


LEN(AS) Returns an integer that indicates the number of characters in the string A$ (including 
trailing blanks). For example: 


FRINT LENCAS) 
od 


Ready 
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Table 5-2 
String Functions (Cont.) 


Indicates a concatenation operation on two strings. For example ““ABC’’+‘‘DEP’”’ is 
equivalent to “ABCDEP’’. “12”+**34”"+56” is equivalent to “123456”. 


CHRS(N%) Generates a 1-character string having the ASCII value of N (see Table 5-2). For 
example, CHR$(65) is equivalent to ‘‘A”. Only one character can be generated. 


ASCI(AS) Generates an integer that is the ASCII decimal value of the first character in A$. For 
example, ASCII(“‘X’’) is equivalent to 88, the ASCII equivalent of X. If B$ = “XAB”, 
then ASCII(B$) = 88. 


DATES(N%) Where N%=0, this function returns the current date in the form: 
<day>-<month>-<year> 


For example: 
12-AUG-72 


This quantity can be printed on output by simple reference to the function. It should 
be noted that dates are output using both upper and lower case letters. When the 
output device is not capable of generating lower case letters, the ASCII values still 
imply lower case. Where N%Z<>0 the function translates N% into a date string. (See 
Section 8.8.) If the run-time system was generated with the numeric data option, 
12-Aug-72 is returned as 72.08.12. 


INSTR(N1%,A$,B$) Indicates a search for the substring B$ within the string A$ beginning at character 
position N1. Returns a value of 0 if B$ is not in A$. Returns the character position of 
B$ if BS is found to be in A$ (character position is measured from the start of the 
string with the first character counted as character |). For example: 


FRINT INSTR OSA ASs “OR? >) 


a5) 
Ready 


If BS is a null string (BS = “”’), the INSTR function returns the value 1. The null 

String is a proper substring of any string and is treated conventionally as the first element 
of A$ in null string search operations. In addition, if both A$ and B$ are null strings, 

the INSTR function returns the value 1. 


SPACES$(N%) Indicates a string of N spaces, used to insert spaces within a character string. 

NUMS(N) Indicates a string of numeric characters representing the value of N as it would be out- 
put by a PRINT statement. (NUM$(n)=(space)n(space) if n>0 and NUM$(n)=- n(space) 
if n<O. For example: 


FRINT NUM$ 074450987021 34) 
°/4651E 13 


Ri @ etch 
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Table 5-2 
String Functions (Cont.) 


NUMIS(N) Yields a string of numeric characters numerically equal (or approximately equal) to the 
integer or floating point value N. This is similar to the NUM$ function, except that no 
spaces nor E-format results are returned. It may be used to convert an integer or 
floating point value for use as a string function operand. For example: 


PRINT NUMI& CRT 3 
Se L4ALSP 265358979 


Re chs 


PRINT NUML#E C97. SXS04546,2343.,035°5-1) 
2 PE&P7 SE? 6 FELGAP SS 


Re acy 


VAL{(AS) Computes the numeric value of the string of numeric characters A$ (may include 
digits, +, -, . and E) and returns it as a floating point number. If A$ contains any 
characters not acceptable as numeric input with the INPUT statement, an error results. 
For example: 


PRINT VAL C414.3E~-4° 3 
000143 


Rie chy 


TIMES(N%) Where N%=0, this function returns the current time of day as a string. For example: 


01:30 PM 


Where N%<>0, the function translates N% into a time string (See Section 8.8). If the 
run-time system was generated using the 24-hour time option, 01:30 PM is returned as 
13:30 followed by 3 spaces. TIME$ always returns an 8-character string. 


STRINGS(N1%,N2%) Creates a string of length N1% and characters whose ASCII decimal value is N2%. For 
example, to create a string Y$ composed of 10 space (blank) characters CHR$(32%), 
execute the following statement: 

Y¥é = STRING# CLO» 3232 


Fee 3 chs 


See Section D.2 for the decimal values of ASCII characters. 
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Table 5-2 
String Functions (Cont.) 


CVT$$(S$,M%) Converts the source character string $$ according to the decimal value of the integer 
M%. The bits of M% are interpreted as follows. 


1% Trim the parity bit. 
2% Discard all spaces and tabs. 


4% Discard all carriage return (CR) line feed (LF), form feed (FF), escape (ESC), 
rubout (DEL), and fill or null (NUL) characters. 


8% Discard leading spaces and tabs. 
16% Reduce spaces and tabs to one space. 
32% Convert lower case to upper case. 
64% Convert square brackets to parentheses; i.e., [ to ( and | to ). 
128% Discard trailing spaces and tabs. 
256% Disallow alteration of the string except parity bit trimming. 


These bits can be used in combination. If M% is given as 21%, for example, the result is 
the same as if the user had used three CVT$$ functions with M% values of 1%, 4%, and 
16%. 


This function is described in detail in Section 12.5 


XLATE(S$,T$) Translates source string S$ from its existing storage code to a code indicated by the 
table string T$, and returns the translated form of string S$ as the target string. 


For a complete description of this function, see Section 12.7. 


NOTE 
The following functions are for use in connection 
with the string arithmetic feature. The arguments 
A$ and BS can be either string variable names, string 
expressions, or string constants and should consist 
entirely of numeric characters with an optional decimal 
point. See Section 5.6 for further details on string 
arithmetic. 


SUM$(A$,B$) Yields the arithmetic sum A$ + BS of the numeric strings A$ and B$. For example: 


PRINT S1i% 
12349.1789 


Reacts 


PRINT SUM#(¢S1¢9 “89. 45454545457) 
124398 .6334454545 


Fe 3 Cy 


id 
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Table 5-2 
String Functions (Cont.) 


DIF$(A$,B$) Yields the arithmetic difference, A$-B$, of numeric strings A$ and B$. For example: 


PRINT BS 
9876.94324 


Re actu 


FRINT DIFFS CBS: “78.89 7) 
9797 65521 


Rea sch 


PRODS(A$,B$,P%) Yields the product, A$ times B$, with rounding to P% places. For example: 


FRINT Atty RE 
12345.4/78% 9B76. 543521 


Re ach 


PRINT PROD CAs Bb: OA) 
121932631.11263%5 


Re acy 


QUO$(A$,B$,P%) Yields the quotient, A$ divided by B$, with rounding to P% places. For example: 


FRINT Cd 


Je 


Re aciy 


VO$=QhOb CC Hy 1.77779 3A) 


Rea chy 


FRINT VO 
1.949 


Re aciy 
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Table 5-2 
String Functions (Cont.) 


PLACES(A$,P%) Rounds A$ to P% places. For example: 
ALE=FLACES CAB, INT CR. 73) 
Re acl 


PRINT Alt 
12345.679 


Pie cits 
COMP%A$,B$) Yields a truth value based on the result of a numeric comparison, as follows: 
-lif A$ <B$ 
0 if A$ = BS 
1 if AS > BS 
For example: 


TH=COMPA CAE es ALF} 


Pie echt 


PRINT 
~4 


Ree icity 


PRINT COMPACALBS A? 
1 


5.5.1 User-defined String Functions 
Character string functions can be written in the same way as numeric functions. (See Sections 3.7.3 and 8.1.) The func- 
tion is indicated as being a string function by the $ character after the function name. 


User-defined string functions return character string values, although both numeric and string values can be used as 
arguments to the function. For example, the following multiple-line function (see Section 8.1) returns the string which 
comes first in alphabetical order: 


100 QEF FNF$CAGs BS) 

\ FN &=AG 

\ IF AtsBé THEN FNFS&=RS 
119 FNENYD 
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The following function combines two strings into one string: 
10 DEF FNCSOX#$s Y$I=XEb 7H 
Numbers cannot be used as arguments in a function where strings are expected or vice versa. Line 80 is unacceptable: 


LO QEF FNA$CA$) = CHRECLENCA$I41) 


OO LET 2=FNAG C4) 


The message: 
Arguments don’t match at line &O 
is printed. 
The following code is a string function which returns the leftmost five characters from the sum of three arguments: 


LISTNH 


fo GEF FNAEC Xs Y¥s2) x LEFT ONUMS (X4+44+29 932 
SO PRINT FNASCLOGs 2093) 
S27 Oo/ EN 
Re sciy 
RLUINANE 
123 


Ra sci 


NUM S$(123) is a 5-character string, as follows: 
“(space)1 23(space)” 


5.6 STRING ARITHMETIC FEATURE 

The optional string arithmetic feature comprises seven functions that treat numeric strings (i.e., strings consisting 
entirely of an optional leading sign, numeric characters, and an optional decimal point) as arithmetic operands. This 
feature offers greater arithmetic precision than floating point with large numbers or with fractions and eliminates the 
need for scaling. As with any string value, numeric string variable names must be suffixed with a dollar sign ($) 
character, and numeric string constants must be bounded by quotation marks (°’) or apostrophes (’). The seven string 
arithmetic functions are described in Table 5-2. 


5.6.1 String Arithmetic Precision 
The maximum size of a string arithmetic operand is 60 characters, including the sign and the decimal point. 


P% is an integer expression. The value of P% determines the level of arithmetic precision in the result of a PRODS, 


QUO$, or PLACES function. P% can be positive or negative. A positive P% value less than 5000 rounds the result 
to P significant digits to the right of the decimal point. For example: 
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_LISTNH 
LOO EXTENT 
TALLOWS LONG VARTARBLE NAMES 
110 INFUT “ENTER TWO NUMERIC STRINGS TO BE MULTIPLIED? 


STRING. AS* STRING. BS 
\ INFUT “TO HOW MANY DECIMAL PLACES’ sFNOX 
120 PR&=PROUS (STRING. A$sSTRING,. BS 9FNQOZ) 
\ FRINT “ANSWER IS “sFRS 
32767 ENT 


Ready 


RUNNH 

ENTER TWO NUMERIC STRINGS YO BE MULTIPLIED? 36453.3442 °879,0004532/ 
TO HOW MANY DECIMAL FLACES? 12 

ANSWER IS 49622516.7186564072 


Ready 


RUNNH 

ENTER TWO NUMERIC STRINGS TO BE MULTIFLIED? .0000906754310134,.2340345 
TO HOW MANY DECIMAL FLACES? 10 

ANSWER IS .0121717288 


Ready 


Negative P% causes the result to be effectively divided by 10° (P%) and rounded (P%) places to the left of the decimal 
point. For example: 


100 PRINT “ENTER A LARGE NUMBER‘ 
\INFUT At 
\NIF At = 70% THEN 150 


110 LET BS = SUM# CAS» BS) 
| ACCUMULATE TOTAL OF INFUT STRINGS 
120 GO TO 100 
130 RE = FLACES(Rby~-SA) 
140 PRINT “TOTAL ITS AFPROXIMATELY ’s Bs * MILLION’ 


32767 ENT 
Ready 
The following can be used in place of lines 150 and 160. 
150 FRINT “TOTAL IS APPROXIMATELY “sPLACE$(R49-6%)% *° MILLION’ 
The result is always rounded if P% is less than 5000. 
To truncate a result instead of rounding, specify P% in the form: 
P% + 10000 


and the result will be truncated at positive P%. 
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5.6.2 Combining String Functions 
String arithmetic functions can be nested (i.e., used as operands in other string arithmetic functions) to specify complex 
arithmetic or algebraic operations. For example, the following LET statement 
X=A*B+C/D 
might be written 
X$ = SUM$(PROD$(A$,B$,10), QUO$(C$,D$,10)) 
in string arithmetic. The following statement 


X$ = PRODS(AS,B$,10) + QUOS(C$,D$,10) 


is legal, but concatenates the product and quotient strings instead of summing them. 


CHAPTER 6 
INTEGER AND FLOATING POINT OPERATIONS 


Numbers on the system can be represented and manipulated in either integer, floating point, or string format. The 
implications of representing numbers in a certain format and the resultant benefits are described in this chapter. 
Certain operations involving integer numbers are more efficient if performed using a forced one-word integer 
format. The specification of a forced integer format and the possible integer operations are described in Section 
6.1 through 6.6. The results of performing operations by mixing the formats are described in Section 6.7. Opera- 
tions using standard floating-point arithmetic and floating-point scaled arithmetic are performed as described in 
Section 6.8. 


6.1 INTEGER CONSTANTS AND VARIABLES 

Normally, all numeric values (variables and constants) specified in a BASIC program are stored internally as floating- 
point numbers. If operations to be performed deal with integer numbers, significant economics in storage space can be 
achieved by use of the integer data type (which uses only one computer word per value). Integer arithmetic is also 


significantly faster than floating-point arithmetic. Integer variables (and constants) can assume values in the range 
- 32768 to +32767. 


A constant, variable or function can be specified as an integer by terminating its name with the % character. For 
example: 


100% A%  FNX%Y) 
4% Al%  ENLIAN%,L%) 


The user is expected to indicate where an integer constant is to be generated by using the % character. Otherwise 
a floating-point value is normally produced. 


When a floating-point value is assigned to an integer variable, the fractional portion of that number is lost. The number 
is not rounded to the nearest integer value. (A FIX function is performed rather than an INT function see Section 3.7.) 
For example: 


GA. tel 
Or 
AA <a ear j ¢ ¥Y 


causes A% to be assigned the value - 1. 


6.2 INTEGER ARITHMETIC = 
Arithmetic performed with integer variables is performed modulo 2 16. The number range - 32,768 to +32,767 is 
treated as continuous, with the number after +32,767 equal to - 32,768. Thus, 32767% + 2% = -32767% and so on. 


Integer division forces truncation of any remainder: for example 5%/7%=0 and 199%/100%=1. Operations can be 


performed in which both integer and floating-point data are freely mixed. The result is stored in the format indicated 
as the resulting variable, for example: 
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L125 LET XZ = NA + FNACK) &2 


The result of the expression on the right is truncated to provide an integer value for X%. The result of mixing integer 
and floating-point data is explained in Section 6.7. 


Where program size is critical, the use of the % character to generate integer values is encouraged, as it uses significantly 
less storage space. For example: 


1L2Q FOR I4Z=1% TO 102% 
takes less storage space and executes faster than: 
L2O FOR I=1 TO 10 


6.3 INTEGER I/O 

Input and output of integer variables is performed in exactly the same manner as operations on floating-point 
variables. (Remember that in cases where a floating-point variable has an integer value it is automatically printed as an 
integer but is still stored internally as a floating-point number and hence takes more storage space.) It is illegal to 
provide a floating-point value for an integer variable through either a READ or INPUT statement. For example: 


LISTNH 
119 READ AyBAyCrDTAveE 

\ PRINT AvBAZsCeTAvE 
600 VATA 267¥39495.796.8 
Re acy 
RUNNE 


Zate format error at line 110 
Reach 

when line 600 is changed to 
600 YATA 2+ 7324952 G.8 

the following is printed: 


RUNNH 
27 3 4 55 6.8 


Reacy 
6.4 USER-DEFINED INTEGER FUNCTIONS 
Functions can be written to handle integer variables as well as floating-point variables (see Section 3.7.3 and 8.1). 
A function is defined to be of integer type by following the function name with the % character. 


A function to return the remainder when one integer is divided by another is shown below: 


Lio DEP PNRACIAsJZ) = [A-J4 & Cl“z/ 
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and could be called later in a program as follows: 
2900 PRINT FNRACAAr LIA) 


Integer arguments can be used where floating-point arguments are expected and vice versa as the system performs the 
necessary conversions. However, strings cannot be used where numbers are required (or vice versa). 


73 DEF FNAACXA) = XA - 12% 
BO LET 24 = FNAZC12.34) 


is acceptable. Z equals 11 after line 80 has been executed. 


6.5 USE OF INTEGERS AS LOGICAL VARIABLES 

Integer variables or integer-valued expressions can be used within IF statements in any place that a logical expression 
can appear. An integer value of 0% corresponds to the logical value FALSE, and any non-zero value is defined to be 
TRUE. The logical operators (AND, OR, NOT, XOR, IMP, EQV) operate on logical (or integer) data in a bitwise 
manner. The integer - 1% (which is represented internally as 16 binary 1’s) is normally used by the system when a 
TRUE value is required. 


Logical values generated by BASIC always have the values - 1% (TRUE) and 0% (FALSE). 


The following immediate mode sequence illustrates the use of integers in logical applications in an IF statement: 


iP “1 THEN PRIN. “TRUE ELSe- PRINT “FALSE ’ 
TRUE 


Reacdy 
IF 424 ANID 24 THEN FRINT “’TRUE’ ELSE FRINT “FALSE? 
FALSE 
Reachy 


iF ~i4% AND. O4 THEN PRINT 1 ELSE PRINI- 2 


o 
Re acy 


IF -1% IMF -1% THEN PRINT ‘T’ ELSE PRINT ‘F° 
T 


Re sci 


TF -440 AOR ~-17 THEN PRING “TRUE ELSE PRINT “FALSE * 
TRUE 


Fie schy 
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A relational expression or a logical operation on relational expressions (see Section 2.6.5) can be used in place of an 
integer expression. Consider the following expression, which assigns the value of a logical product of relational expres- 
sions to an integer variable. 


LISTNH 
100 Xx 
\ 
110 Lz 
\ 
32767 E 
Reacy 


RUNNH 
0 


Re aciy 


6.6 LOGICAL OPERATIONS ON INTEGER DATA 
BASIC-PLUS permits a user program to combine integer variables or integer valued expressions using a logical operator 
to give a bit-wise integer result. 


An integer value is represented internally in 2’s complement notation as a sign bit and 15 data bits. Refer to Appendix E 
for the description of the internal format of an integer. In a logical operation, the corresponding bits of two integer 
values are combined on a bit-by-bit basis determined by the logical operator used. The logical operators are defined in 
Section 2.5.5. 


For the purpose of logical operations, A and B as defined in the truth tables shown in Section 2.5.5 are modified. A 
becomes the condition of one bit in one integer value, and B becomes the condition of the bit in the corresponding bit 
position of another integer value. The truth tables are as follows. 


A | NOTA 
l 0 
0 l 
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The result of a logical operation is an integer value generated by combining the corresponding bits of two integer values 
according to the rules shown in the truth tables above. For example, the following command prints the logical product 
of the integers 85% and 28%. 


PRINT @34 AND 28% 
2Q 


Rie chy 


Each bit in the internal representation of 85% is combined with each corresponding bit in the internal representation 
of 28% according to the rules in the AND truth tables. By consulting the AND (logical product) truth table, it can be 
seen that a bit is generated in the bit position of the result only if both bits are 1 in the corresponding bit position of 
the integer values 85% and 28%. The resultant value of 20 printed by BASIC is the integer value of the bits set in the 
internal representation of the logical product. 


Note that two values that would yield “‘true” (< > 0) values if considered independently can yield a “false’’ (=O) result 
if combined in a logical product expression. For example: 


2% AND 4% 


yields a logical product of 0, because they have no set bits in common. This potential problem can be avoided by using 
-1% as one of the logical operands. 


The following command prints the logical sum of 85% and 28%. 


FRINT 854 OR 28% 
93 


Reacdy 
From the OR (logical sum) truth table, it can be seen that a bit is generated in the bit position of the result if either the 
corresponding bit of the internal representation of 85% or 28% is a 1. The resultant value of 93 printed by BASIC is 
the integer value of the bits set in the internal representation of the logical sum. 


The following command prints the logical difference of 85% and 28%. 


FRINT 85% XOR 284 
73 


REATIY 


The result of any logical operation can be assigned to an integer variable. For example, the following statement assigns 
a logical product to an integer variable which, in turn, can be printed. 


LISTNH 

100 CA” = BSA ANDI 28% 
\ FPRINT CZ 

Reacty 


RUNNE 
20 


Re acy 
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The logical operation can be used to mask a particular bit pattern. For example, the following BASIC-PLUS statement 
is used to generate the value of the low order eight bits, L%, of an integer word, W%. 


100 La = WA AND 252 


The internal representation of 255% is such that the low order eight bits (bits 0 through 7) are all 1, and the high 

order eight bits (bits 8 through 15) are all 0. The AND operation (logical product) generates a bit in L% only if a bit 
appears in the corresponding bit position of both W% and 255%. Since 255% is known to contain all 0’s in the high 
order bits and all 1’s in the low order bits, the result L% reflects the presence of bits set and cleared in the low order 
eight bits of W%. Such a use of a bit pattern is called masking, where the internal representation of 255% is such that it 
provides a mask to hide one portion of a bit pattern (the high order bits of W%) and reveals another portion of a bit 
pattern (the low order bits of W%). 


In summary, integer values can be combined as described in Section 6.2 using arithmetic (mathematical) operators to 
give arithmetic results. Integer values can be compared using relational operators (see Section 2.5.4) and can be com- 
bined using logical operators (see Section 2.5.5) to give either a TRUE or FALSE result as described in Section 3.5 or 
to give 0% for false or -1% for true as described in Section 6.5. In any case, the results of all relational and logical 
operations are integer values. When a logical operation is performed in conjunction with arithmetic and relational 
operations, the priority scheme as described in Section 3.5 is used to determine the hierarchy of operations. 


Thus, with the feature described in this section, integer variables and integer-valued expressions can be operated on by 
AND, OR, XOR, EQV, IMP and NOT to give a bit-wise integer result. 


6.7 MIXED MODE ARITHMETIC 

The user can perform arithmetic operations using a mix of integer and floating-point numbers. To force a floating-point 
representation of an integer constant, terminate it with a decimal point. Use the % character as described in Section 6.1 
to force an integer representation of a constant. Constants without a decimal point or % character are termed ambiguous. 
The remainder of this section describes the results of arithmetic operations using a mix of numbers. 


If both operands of an arithmetic operation are either explicitly integer or floating point, the system generates, 
respectively, integer or floating-point results. If one operand of an arithmetic operation is an integer and another is 
floating-point, the system converts the integer to a floating-point representation and generates a floating-point result. 
For example: 


ago, Saw & Sate 5 See eS ae Wee ee Ge ee 
8) eo oa mo 
Ke azide 


In the first two operations, the system generates the explicit results; in the second two, the system converts the explicit 
integer and generates floating-point results. 


When an ambiguous constant appears in an arithmetic expression (for example, 10 as opposed to 10% and 10.), the 
system represents it in integer format if an integer variable (for example, I%) or an integer constant (for example, 3%) 
occurs anywhere to the left of the constant in the expression. Otherwise, the system treats the ambiguous constant as 
a floating-point number. The system performs the operation according to the rules described above. For example, 


PRINT 37/23 17284 1S 


3 eee oe 
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In the first operation, the system treats the 2 as an integer because an explicit integer representation appears to the left 
in the expression. In the next two operations, the system treats the ambiguous constants as floating-point numbers 
since no explicit integer variable or constant appears to the left of the ambiguous constant in the expression. 


Since the format of the results determines the results of many operations, the user must explicitly impose the correct 
format by use of the percent sign or the decimal point. For example, compare the following calculations, assuming 
A (2%) = 0 in each expression. 


PRIN Ates? + (827674233 Oi25) + 032767. + 2) 
“62/7 G7 32769 


Reacy 


The result of the first expression is guided by the appearance of the percent sign and forces an integer result. The deci- 
mal point in the second expression forces results in floating-point format. The same principle applies in the following 
example. 


Peat te. + 1/atae + 1/2 141k 


5 eee Se eee Ge 
Re sci 


The choice of an explicit percent sign or the decimal point determines the format of the result, thus enabling the user to 
control the result. 


6.8 FLOATING-POINT AND SCALED ARITHMETIC 

Floating-point numbers occupy either two 16-bit words or four 16-bit words of storage in memory. With the single 
precision package, two words are used; with the double-precision package, four words are used. Appendix E describes 
the internal format of the two packages. 


With the 2-word format, the user can accurately represent numbers up to six decimal digits, and, with the 4-word for- 
mat, numbers up to 15 decimal digits. Both formats allow numbers in the range 10°-38 to 10° 38 approximately. An 
attempt to assign or compute a number outside the allowed range causes the FLOATING POINT ERROR condition 
(ERR = 48). 


The system performs output of numeric results of floating-point calculations as described in Section 2.6.1. To perform 
output of numbers larger than six digits, the user can tailor the format as described in Section 10.3.3 for the PRINT 
USING statement. 


Usually fractional numbers cannot be represented exactly in binary notation, and certain calculations in floating point 
result in an accumulative error. For example, the following calculation, run in standard 4-word floating point, results 
in an accumulative error because the floating point-fraction .01 is not represented internally as that precise value. 


_ISTNH 

106 X= ¢ 

1106 R- & 4 3 O17 FGR TY = 12 10. -106007 
1290 PRINT X ~ 100. 

32767 ENT 

Reacty 

RUNNE 


~.217/7636E-i1 


Re esciy 
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If no accumulated error exists, the result is 0. Running the example code on a system using the 2-word format gener- 
ates a much greater accumulated error (approximately .00295). 


To perform decimal calculation on a system having the double-precision floating-point (4-word) math package, the user 
can employ the scaled-arithmetic feature to avoid or reduce accumulated error in the fractional part of a number. The 
user can specify the number of decimal places in fractional numbers by use of the SCALE command. Systems with 
2-word precision do not have scaled arithmetic. 


NOTE 
Scale arithmetic is included with the double-precision pack- 
age primarily for compatibility with existing programs. The 
string arithmetic feature provides a more flexible and 
generally easier-to-use method for improving arithmetic 
precision. 


With the scaled-arithmetic feature, the user can select a scale factor of 0 to 6. The system uses the scale factor to 
preserve the accuracy of fractional numbers to that number of decimal places. The value 0 is a special scale factor 
which disables the scaled-arithmetic feature and allows the system to perform calculations using standard double- 
precision floating-point arithmetic. The scale factor is 0 at log-in time. 


With a scale factor of n between 1 and 6 in effect, the system, upon input of a floating-point number, internally moves 
the decimal point n places to the right and truncates it to an integer. The system performs all subsequent calculations 
with the floating-point integers and, in turn, translates the result of each arithmetic operation into a floating-point inte- 
ger with the scale factor n. On output, the system moves the decimal point to the left n places (descales) and passes 
the result to the PRINT or PRINT USING routines to format. 


A scale factor between | and 6 determines the accuracy of fractional numbers. For example, with a scale factor of 2 in 
effect, the following statement, upon input, causes the system to move the decimal point two places to the right. 


X = .O1 


If any rounding is necessary, the system does it at this point. The system then converts the result, 1, to a floating-point 
representation. Similarly, .1 becomes 10 internally and all numbers less than .005 become 0. 


The scaled-arithmetic conversion thus avoids the loss of precision inherent in representing fractional numbers in binary 
notation since the system can represent the integer accurately in floating-point format. This feature, therefore, allows 
more predictable arithmetic results. For example, running the following calculation with a scale factor of 2 yields a 0 
result. 


LISTNH 

100 X=Q ¢ 

110 AMER OE OI PGR TS =" FS 70 - 1ee0Gy 
120 FRINT X -— 106, 

32767 ENT 


Ready 


RUNNH 
Q 


Ready 
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The scaling factor of 2 eliminates the inaccuracy in representing a fraction two places to the right of the decimal point. 


The range of integer numbers which can be represented accurately decreases according to the scale factor in effect. 
For example, with a scale factor of 2 in effect, two of the 15 digits must be used to represent the two digits of fraction. 
There remain 13 places to accurately represent the integer portion of the number. 


With a scale factor in effect, the system handles output by PRINT and PRINT USING statements in the standard 
manner. The PRINT statement still handles six digits or less and uses the E format for numbers larger than six digits. 
The PRINT USING statement formats numbers according to the specified string. 


The mathematical functions described in Section 3.7 can be used in conjunction with the scaled-arithmetic feature. 
With a non-zero scale factor in effect, the system automatically descales the number passed, computes the value of 
the function, and converts the value returned to an appropriately scaled floating-point integer. No rounding occurs; 
places outside the scale factor range are truncated. 


6.8.1 The SCALE Command 
The following description of the SCALE command is intended only to show briefly how to use it and how it works. For 
a more detailed description, refer to the RSTS/E System User’s Guide. 
To specify a scale factor, enter the following command: 
SCALE <scale factor> 
The scale factor must be a decimal integer from O to 6. That scale factor remains in effect until another SCALE com- 
mand is given, or until log-off. When a program is compiled, the current job scale factor is established as the scale 
factor associated with the stored program. 


SCALE is a RSTS/E command, not a BASIC-PLUS statement; a program cannot refer to or modify a scale factor. 


Typing SCALE without a scale factor value causes the current job scale factor to be printed. If the current program has 
an associated scale factor that differs from the job scale factor, the program scale factor is also printed. For example: 


SCALE 
vd 
ees scale factor 
Current job scale factor 
READY 


If the current job scale factor differs from the scale factor of the current program, the job scale factor takes precedence. 
A user might load a compiled program using the RUN command and then discover that the scale factors are different. 
To run under the program scale factor, the user must: 


1. Change the current job scale factor to that of the program. 
2. Use the OLD command to load the source version of the program, this time under the desired scale factor. 
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CHAPTER 7 
MATRIX MANIPULATION 


This chapter deals with BASIC-PLUS matrix manipulation commands. Matrices can be composed of variables of any 
type. A single matrix, however, is composed of a single type of data; floating point, integer, or character string. The 

MAT operations do not set the zero elements [A(O), or B(O, n) and B(n, 0)] of the specified matrix to conform with 
the requested operation. 


7.1 BASIC-PLUS ARRAY STORAGE 

A BASIC-PLUS program can define the size of a matrix in one of two ways: explicitly, by including the matrix in a 
dimension statement, or implicitly, where the matrix does not appear in any dimension statement. Implicitly 
dimensioned matrices are assumed to have ten elements in each dimension referenced (size 10 for a 1-dimensional 

matrix and size 10-by-10 for a 2-dimensional matrix, with each dimension also having a zero row and column). Implicitly 
dimensioning the matrix A(I, J), for example, has the same effect as explicitly including the following statement: 


Re acs 
109 OIM ACLO»s10) 


Dimensioning a matrix (explicitly or implicitly) establishes two quantities for the system: the default number of ele- 
ments in each row and column and the maximum number of elements in the matrix. Through use of the MAT com- 
mands, described in this chapter, the program can alter the number of elements in each row and the number of columns 
in the matrix as long as the total number of elements does not exceed the number defined when the matrix was 
dimensioned. Changing the number of elements in either or both dimensions is termed redimensioning the matrix. 


When a matrix is redimensioned, the user program should take care not to reference elements outside the currently 
dimensioned range of the matrix. For example, if the range of matrix A is 5 by 7, referencing A(3,8) is improper and, 
although no error is generated, generally results in some element elsewhere in the matrix being destroyed. 


7.2 MAT READ STATEMENT 
The MAT READ statement is used to read the value of each element of a matrix from DATA statements. The format 
of the statement is as follows: 


MAT READ <iist of matrices> 
Each element in the list of matrices indicates the maximum amount of the matrix to be read (which cannot be greater 


than the dimensioned size of the matrix). The individual elements are separated by commas. If the matrix name is 
used without a subscript, the entire matrix is read. For example: 


100 DIM AACAQ»20) 
L190 MAT READ Ax 


The above lines read a 20-by-20 matrix of floating-point data. Data is read row by row; that is, the second subscript 
varies most rapidly. If line 110 had read: 


L190 MAT READ AXCSs15) 


a 5-by-15 matrix would be read and the matrix A would be redimensioned. | 
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7.3 MAT PRINT STATEMENT 
The MAT PRINT statement prints each element of a 1- or 2-dimensional matrix. The statement is of the form: 


b 


MAT PRINT. <matrix name> , \ 


If the matrix name consists of an unsubscripted matrix name, the entire matrix is printed. If the matrix name is sub- 
scripted, then the subscript indicates the maximum size of the matrix to be printed (but does not redimension the 
matrix). Only one matrix can be output by a single MAT PRINT statement. 


If the matrix name is followed by a semicolon (;), the data values are printed in a packed fashion. If the matrix name is 
followed by a comma (,), the data values are printed across the line with one value per print zone. If neither character 
follows the matrix name (the null case), each element is printed on a separate line. 


1900 DIM ACIOs10O) »BC20%20) 
110 MAT FRINT Ay» 

[PRINT 10x10 MATRIX: FACKED FORMAT 
120 MAT FRINT BC494)» 


IFRINT 4-BY-6 MATRIX» 3S ELEMENTS FER LINE 
One-dimensional arrays can be printed in either row or column format. 
22 MAT FRINT ¥V 
where V is a singly-dimensioned array, prints the array V as a column matrix, and 
aed MAT FRINT Vy» 
prints the array V as a row matrix, five values per line. 
a MAT FRINT Vy» 


prints the array V as a row matrix, closely packed. For example: 


LISTNH 
100 NIM AC7Z)» XCD) 
110 MAT REA A»xX 
120 MAT FRINT Ay 
\PRINT 
\MAT FRINT X 
2O0 QATA 2lvy22923% 249359 36s 37 951 2953 9 S42 SS 


32767 END 


Re acy 
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ea 24-35 36 = -S7 


Two-dimensional arrays are printed in ascending format. For example: 


LISTNH 


100 
L109 


120 


32767 

Ready 

RUNNH 
Lot 


2Q1 


Re schy 


NIM AC293) 
ran i424 -=-32 “30 22 
\ FOR JA = 1% TO 3% 
\N LET ACIAsJIZ) = IXK100% + J% 
\ NEXT J2 
\ NEXT Ita 
\ FRINT 
MAT PRINT Ay 
EN 
102. 103 
202 203 


7.4 MAT INPUT STATEMENT 


The MAT INPUT statement is used to input the value of each element of a predimensioned matrix. The statement is of 


the form: 


line number MAT INPUT <list of matrices> 


Input is read from the keyboard, as with a normal INPUT statement, and a ? character is printed when the program is 
ready to accept the input. The LINE FEED key can be used to continue typing data on succeeding lines. The RETURN 
or ESCAPE key is used to enter the data to the system. MAT INPUT does not affect row 0 or column 0 of the 


matrix. 


The MAT INPUT statement allows input of integer, floating-point or character string values depending upon the variable 
names. Where more than one matrix is to be input by the same MAT INPUT statements, the names are separated by 


commas. For example: 


1O0 
110 


NIM AAC20) 2 BCLS) 
MAT INFUT AXsB 
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causes the program to input 20 integer elements for the array A% and 15 floating-point values for the array B. 
Where an array or matrix element is specified, for example: 
ZOO MAT INFUT NAC25) 


only 25 elements of the array are input, regardless of the number of elements originally specified when the array was 
dimensioned. The array is then redimensioned. For example: 


LISTNH 

100 DIM AC2ZO0r20) 

110 MAT INFUT AC4 93) 
120 PRINT 


\ MAT FRINT Ay» 
52767 ENT 


REATY 
RUNNH 

P SrBr 4 Se QvOrl eG. 2xO0vGeBv2e7 93-0196. 34S 
wd 3) 445 

2 QO 1 

92 0 6+8 

ae? 3+O1 6+ 345 
REALTY 


The matrix A is redimensioned in line 100. The INPUT statement proceeds to accept input until the entire matrix has 
been read or the RETURN or ESCAPE delimiter is encountered. Several lines can be input by terminating the physical 
keyboard line with a line feed to indicate continuation on the following line. 


Following the input of a matrix, the two variables NUM and NUM2 contain the number of elements input. NUM 
contains the number of rows input or, for a 1-dimensional matrix, the number of elements entered. NUM2 contains 


the number of elements in the last row. For example, the following example program inputs a variable size matrix (up 
to 10-by-10): 


LISTNH 

100 QIM ACIQs10) 

110 INFUT “TYPE MATRIX DIMENSIONS UF TO 10910’5NoM 
\ MAT INFUT ACN»M) 

120 PRINT “NUM =“’sNUMy»y “NUM2 =’ SNUM2 

130 TF NUMKNUM2=NKXM THEN FRINT “MATRIX FILLED? 
\ GO T0 32767 

140 FRINT “MATRIX NOT FILLED’ 


32/767 END 


Ready 


7-4 


Matrix Manipulation 


RUNNEH 

TYPE MATRIX TIMENSIONS UF TO 10210? 428 

P L259 45hs S54 ye POFs 76S 4GGyLeSeL yee Se4ySvGe7 ve BrP eOrOrPv By 7945 
NUM = 3 NUM? = 6 

MATRIX NOT FILLED 


Ready 
Checking the contents of the matrix 


MAT FRINT Ags 
tee 856. 345-909 763 456 123. 1 


Reacy 
Unlike the INPUT statement, no text string can be output with the MAT INPUT statement. For example: 


1090 MAT INFUT “CONTENTS OF MATRIX’ ¢ Az 
?FSunmtax error at line 100 


Reachy 


7.5 MATRIX INITIALIZATION STATEMENTS 
A matrix initialization statement allows the user to create initial values for the elements of a matrix. The statement is 


of the form: 
(DIM1, DIM2) 


MAT <name> = <value> (DIM1) 


The name specified is the name of a predimensioned matrix, and the optional DIM1 and DIM2 specifications indicate 
the size of the matrix to be initialized. When specified, DIM1 and DIM2 cause the matrix to be redimensioned. The 
value can be one of the following: 


Value Meaning 


ZER Sets all elements of the matrix to O (this is true of all matrices when they are 
first created). (Function does not set row 0 or column 0.) 

CON Sets all elements of the matrix to 1. (Function does not set row 0 or column 0). 

IDN Sets up an identity matrix (all elements are 0 except for those on the diagonal, 


A(I,I), which are 1). (Function does not set row 0 or column 0.) 


If no dimensions are indicated (DIM1 and DIM2 are not specified) in a matrix initialization statement, the existing 
dimensions of the matrix are assumed to be unchanged. For example: 
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LISTNH 
100 NIM AC1Os10)% BCLS)» CC20%20) 
110 MAT A=ZER 
ISETS ALL ELEMENTS OF A EQUAL TO 0 
120 MAT B=CON(C10) 
ISETS FIRST 10 ELEMENTS OF & EQUAL TO l 
130 MAT C=I0N¢C1O910) 


ISETS UF AN IDENTITY MATRIX 


32767 END 
Ready 
RUNNH 
Ready 


MAT FRINT Cy 
; ere, Beit ° ese © SAS ere © Sitges © eter © gee * oot ¢ 


Gj Go. SB eh Oe 2 


6 eee ee ee ee 


GO. - 0. 2 Oe eS eS Se 
0. = oe Se Pe 8 
G2 ° 0-6 0. 0s 0 Oe a 
aa ed ee ee 
08-6 6 6-629 1 5: 5 
sre,” geeice,' Gemee ¢ eee © stet * Temton § Saar « ete Ref 
Fe ae Rae a a 
Pe eo a chy 


Again, note that these instructions do not set row O or column 0. 


7.6 MATRIX CALCULATIONS 
Mathematical operators and two intrinsic functions are available for use with matrices. 


7.6.1 Matrix Operations 


The operations of addition, subtraction, and multiplication can be performed on matrices using the common BASIC 
mathematical symbols. 
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Each of the matrix operation statements is begun with the word MAT and is followed by the expression to be 
evaluated. Each of the matrices involved must be predefined in a DIM statement. The subscripts of the matrices need 
not be indicated on the statement. The matrices indicated for any operation must be conformable to that operation. 
A subset of one matrix cannot be indicated as part of an operation. 


110 NIM ACSO)» BC2]5)» CCSO) 
120 MAT C=AtB 
RUNNH 


PMatrix dimension error at line 120 
Reacy 
In order for line 120 to execute properly, line 110 should read: 
110 VIM ACSOd» BBCSO» CCSO) 
Multiplication of conformable matrices is indicated as follows: 


LOO QIM [ClOsS)y CCSv1lO)» RC1IOv103 
110 MAT R = DxKC 


By conformable matrices is meant that the number of columns in matrix D is equal to the number of rows in matrix C. 
The dimensions of the matrix R must be large enough to contain the number of columns in D and the number of 

rows in C. The operation MAT A=A*B or MAT A=B*A is illegal. 

Scalar multiplication of a matrix is performed as follows: 


150 MAT CO = (KRIXA 


Each element of matrix A is multiplied by the scalar value (constant, variable, or formula) K, indicated in 
parentheses. 


The form MAT A=(K)*A is legal. Matrix A can be copied into matrix C (providing sufficient space is available in 
matrix C) as shown below: 


140 MAT C = A 


7.6.2 Matrix Functions 
Functions exist for the performance of transposition and inversion of matrices. 


150 MAT C = TRNCAD 


causes matrix C to be set equal to the transpose of matrix A. That is, C(I,J)=A(J,I) for all I,J; matrix C is redimensioned 
if necessary. For example: 


19 NIM XCiSs25)2 NOSv1l0d» MOSS) 
BO MAT X=TRNCN) 
90 MAT N=INVCM) 
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causes N to be computed as the inverse of matrix M (M must be a square matrix). After the inversion is complete, the 
function DET is set to the value of the determinant of matrix M. (If the matrix being inverted is sufficiently singular to 
make it impossible to complete the inversion, the message CAN’T INVERT MATRIX is printed.) The value of DET, 
then, can be used in subsequent computations as a formula value, as with any other function. For example: 


LISTNH 
OQ 


210 


wae Q 


Re acy 


MAT A = INVCX) 

\DL=QET 

MAT B = TNVCAD 

\0220kT 

IF td=1/02 GO TO 340 ELSE PRINT “RELATIONSHIF TRUE’ 


Matrix inversion, like the other BASIC-PLUS matrix operations, does not operate on the elements of the row O and 
column 0 of the matrix; however, inversion destroys the previous contents of these elements. The operation MAT A = 


INV(A) is legal. 
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CHAPTER 8 
ADVANCED STATEMENT FEATURES 


8.1 DEF STATEMENT, MULTIPLE LINE FUNCTION DEFINITIONS 

In Chapter 3 the DEF statement is described as being able to create a 1-line function, which the user can call as an 
element in a BASIC statement. In BASIC-PLUS multiple-line user-defined functions are also possible. The format for a 
multiple-line function definition is as follows: 


DEF FN<identifier> <(dummy arguments)> 

<body of definition> 

FNEND 
The multiple-line DEF function differs from the 1-line user functions by the absence of an equal sign following the 
function name on the first line. (From zero to five arguments of any type or mixture of types can be used.) The value 
returned by the function is the value of FN<identifier>at the time the FNEND statement is encountered, somewhere 
within the multiple-line definition there should be a statement of the form: 


{LET} FN<identifier> = <expression> 


It is the value of this expression which is returned as the value of the function. (There may be more than one such 
statement, as in the example below.) 


The function example below determines the larger of the two numbers and returns that number. The IF-THEN state- 
ment is frequently used in multiple line functions as follows: 


_LISTNH 

100 EF FNMOXs ¥3 

L190 LET FNM=X 

L2G IF Y¥<=X THEN GOTO 30 
130 LET FNM=¥Y 

149 FNENT 

Ready 
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As another example, the following is a recursive’ function that computes N-factorial: 


LISTNH 


100 
10% 


110 
120 
130 
140 
32767 
REALTY 


RUNNH 


DEF FNF CMA) 


IF MA 


= OZ THEN FNF = 1 


\ GO TO 120 


IF MA 


FNENT 
INFUT 
FRINT 
ENT 


= 1A THEN FNF = 1 
ELSE FNF = MA X FNFCMAZ-124) 


“VALUE FOR FACTORIAL ’s MZ 
MAy “FACTORIAL EQUALS’: FNFCMA) 


VALUE FOR FACTORIAL? 6 
& FACTORTAL EQUALS 720 


REALTY 


RUNNH 


VALUE FOR FACTORIAL? 0 
O FACTORTAL EQUALS 1 


REATIY 


Any variable referenced in the body of a function definition which is not an argument of that multiple-line DEF function 
has its current value in the user program. Multiple-line DEF functions can be nested (one multiple-line definition can 
reference another multiple-line definition of itself.) A multiple-line user-defined function may contain transfers of con- 
trol outside its boundaries (via GOSUB, ON ERROR... RESUME, nested function references, or GOTO, for example). 
However, once a function is entered, it must be exited via its FNEND statement. Line numbers within the function 
cannot be referenced from outside the function boundaries except to return to a function that is currently invoked. 

If the program encounters an FNEND statement whose companion DEF FN ... statement has not been executed, an 


error Occurs. 


Generally, transfers out of function boundaries should be avoided, because they may not execute as expected on other 


BASIC systems. 


1The term “‘recursive” refers to an inherently repetitive process in which the result of each cycle is dependent upon the result of the 


previous cycle. 
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“- The parameters with which a user-defined function is called are strictly formal; attempts by the program to modify 
them are cancelled when the function exits to its calling program: 
LISTNH 
1900 NEF FPNECX) 
: L110 X=Q 
\FNB=10 
120 NENT 
: 200 A= 4 
\B=FNE CA) 


\FPRINT Av 
32767 ENT 


Ready 
RUNNH 
1 10 
a, 
Ready 
A is not set to 0 by the function FNB(A). However, any variable referenced in the body of the function definition 
which is not one of the function arguments will retain, after exit from the function, any value assigned to that variable 
during the execution of the function. 
Functions can be written in any type and can contain any variety of argument types. For example: 
a-™ LISTNH 
100 DiF FNASCAsByCA) 
pe ee IF ASB GOTO 130 
120 FNA$=CHRE CA+1 
\ GOTO 140 
130 FNAS=CHRE CAtCZ Dd 
149 FNENT 
2 OO INPUT “VALUES FOR AvBsCA%s Avy Bs CA 
a ee) FRINT “FNA$CA2BsCA) = “SFNAS CARs CZ) 
~~ Saras E.NI 
Ready 
RUNNH 
VALUES FOR ArBsCA?P S497-35924 
FNA$SCAsB9sCA) = = 
, Ready 
RUNNH 
‘ VALUES FOR AvBeCaP 45.295+6798 
FNA$CAsByCA) = 3 
Reacy 
=_ 
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8.2 ON-GOTO STATEMENT 

The simple GOTO statement allows the user to unconditionally transfer control of the program to another line number. 
The ON-GOTO statement allows control to be transferred to one of several lines depending on the value of an expression 
at the time the statement is executed. The statement is of the form: 


ON <expression> GOTO <iist of line numbers> 


The expression is evaluated and the integer part of the expression is used as an index to one of the line numbers in the 
list. For example: 


mi) ON X GOTO 100%200% 400 
transfers control to: 


1. line number 100 if 1.<=x <2. 
2. line number 200 if 2. <<=x <3. 
3. line number 300 if 3.<=x <4. 


Values of x out of this range cause the error message: 


TON statement aut of ranse at line SO 
is printed (or the user can transfer to an ON ERROR GOTO routine with ERR = 58). 


8.3 ON-GOSUB STATEMENT 

The GOSUB and RETURN statements are used to allow the user to transfer control of his program to a subroutine 
and return from that subroutine to the normal course of program execution (see Section 3.8 for details). The ON- 
GOSUB statement is used to conditionally transfer control to one of several subroutines or to one of several entry 
points to one (or more) subroutine(s). The statement is of the form: 


ON <expression> GOSUB <iist of line numbers> 
Depending on the integer value (truncated if necessary) of the expression, control is transferred to the subroutine which 
begins at one of the line numbers listed. Encountering the RETURN statement after control is transferred in this way 
allows the program to resume execution at the line following the ON-GOSUB line. 
An example of the statement follows: 


GQ ON X4~YA GOSUB SO0%93321014 


When line 80 is executed, the value of X%—Y% being either 1, 2, or 3 causes control to transfer to line 900, 933 or 
1014, respectively. If the quantity X—Y is not equal to 1, 2 or 3, the error message: 


TON stetement out of ranse et line 80 
is printed (or the user can transfer to an ON ERROR-GOTO routine with ERR = 58). 


Since it is possible to transfer into a subroutine at different points, the ON-GOSUB statement could be used to deter- 
mine which portion of the subroutine should be executed. 
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8.4 ON ERROR GOTO STATEMENT 

Certain errors can be detected by BASIC during program execution. These errors fall into two broad areas: computa- 
tional errors (such as division by 0) and input/output errors (reading an end-of-file code as input to an INPUT statement). 
Normally the occurrence of any of these errors causes termination of the user program execution and the printing of a 
diagnostic message. 


Some applications may require the continued execution of a user program after an error occurs. In these situations, the 
user can execute an ON ERROR GOTO statement within his program. This statement tells BASIC that a user subroutine 
exists, beginning at the specified line number, which will analyze any I/O or computational error encountered in the 
program and possibly attempt to recover from that error. 


The format of the ON ERROR GOTO statement is as follows: 
ON ERROR GOTO {<line number>} 


This statement is placed in the program prior to any executable statements with which the error handling routine deals. 
If an error does occur, user program execution is interrupted and the user-written error subroutine is started at the line 
number indicated. The variable ERR, available to the program, assumes one of the values listed in Appendix C, the 
complete RSTS/E Error Message Summary. 


When an error is encountered in a user program, BASIC checks to see if the program has executed the ON ERROR GOTO 
statement. If this is not the case, then a message is printed at the user’s terminal and the program proceeds (if the error 
does not cause execution to terminate). If the ON ERROR-GOTO statement was executed previously, then execution 
continues at the specified line number. Then the program can test the variable ERR to discover precisely what error 
occurred and decide what action is to be taken. 


NOTE 
An ON ERROR GOTO statement with an incorrect 
target statement number can cause error messages that 
are confusing or seemingly inappropriate. 


8.4.1 RESUME Statement 

After the problem is corrected (if this is both possible and desired by the programmer), execution of the user program can 
be resumed through use of the RESUME statement (which is placed at the end of the error handling routine, much like 

a RETURN statement in a normal subroutine). The RESUME statement causes the program line that originally caused 
the error to be reexecuted. If execution is to be restarted at some other point within the program (as might be the case 
for a non-correctable problem), the new line number can be specified in the RESUME statement at the end of the error 
handling routine. 


The format of the RESUME statement is as follows: 
RESUME {<line number>} 


For example: 


Od RESUME 
we OO] RESUME 100 


The line 2000 restarts the user program at the line in which the error was detected, and is equivalent to the statement: 


eQugd RESUME © 
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A RESUME or RESUME 0 statement in an error handling routine passes control to the line containing the statement 
which caused the error. If the statement which caused the error is on a multiple statement line, control is passed to 
the DIM, DEF, FNEND, FOR, NEXT or DATA statement immediately preceding it on the line. If none of these six 
statements is present on the line, control passes to the first statement on the line. For example, consider the line: 


530 A=A + 1 \ PRINT A \ FOR MZ = 1% TO 3% 
\ INFUT X¢M%) 
\ NEXT M% 


If an error occurs in the INPUT statement, above, control is passed to the preceding FOR statement on the same line — 
not to the first statement of the line. The loop is not reinitialized, however, and the INPUT statement is retried without 
changing M%. 


For this reason, a DIM, DEF, FNEND, FOR, NEXT or DATA statement on a multiple statement line with error handling 
should be the first statement on a line. Also, the first statement on a line should be the statement which may generate 
the trappable error. Such placement of the statement prevents logic errors and allows any further error to be handled. 
Any other placement of the statement causes logic errors because statements preceding the statement causing the error 
are executed as many times as control is passed back to the line. If the error handling routine must also handle errors, 
the program can pass control to a RESUME statement which, in turn, can pass control to the error handling routine. 


Line 2001 above restarts the user program at line 100 (which can be used to print some terminal message for that 
particular operation). 


A RESUME statement should always be included in the error handling routine. 


8.4.2 Disabling the User Error Handling Routine 
If there are portions of the user program in which any errors detected are to be processed by the system and not by the 
user program, the error subroutine can be disabled by executing the following statement: 


ON ERROR GOTO 0 
which returns control of error handling to the system. An equivalent form is: 
ON ERROR GOTO 


in which case line 0 is assumed. Executing this statement causes the system to treat errors as it would if no ON ERROR 
GOTO had ever been executed. 


Generally, the error handling subroutine detects and properly handles only a few different errors; it is useful to have the 
RSTS system handle other errors, if they occur. For this reason, RSTS allows the ON ERROR GOTO 0 statement to be 
executed within the error subroutine itself. Special treatment is accorded this case, in that the disabling occurs retro- 
actively; the error which caused entry to the error subroutine is then reported and a message printed as though no ON 
ERROR GOTO statement had been in effect. 


As an example of this feature, consider an application in which inexperienced users interact with a BASIC program. 
These users may not know what to type at the terminal, and the program may want to prompt them. The program tells 
the system to allow up to 60 seconds for the user to respond (via the WAIT function, described in Section 8.8) and then 
to alert it that the user has not replied. The program then prints additional information for the user. 


The program below requests the user’s name with the INPUT statement on line 120. The ON ERROR GOTO statement 
is previously executed on line 100. 
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LISTNH 
~ 100 ON ERROR GOTO 1000 
ISET UF ERROR ROUTINE 
110 WAIT( 60) : 
IWAIT 60 SECONDS FOR REFLY 
120 INFUT “YOUR NAME’ ¢N& 
- IGET STUTENT NAME 
150 STOF 
1000 I'THIS IS THE ERROR HANDLING ROUTINE 
1010 IF ERRSS15 THEN ON ERROR GO TO oO 
[WAIT ERRORS ONLY 
L020 PRINT 
ISKIF TO NEW LINE 
| 1030 PRINT ’FLEASE TYFE YOUR NAME’ 
-~ \ PRINT ‘AND THEN HIT “°RETURN" KEY’ 
LOS0 RESUME 
ITRY AGAIN 
32767 E NI 
Reachy 


In this example, if the call to the error subroutine was caused by some error other than the KEYBOARD WAIT 

EXHAUSTED error, the program would exit via the ON ERROR GOTO 0 in line 1010. This permits the appropriate 

error message to be printed on the user’s terminal. Note that exiting via the RESUME at line 1050 causes the INPUT 
“™ statement to be restarted. 


8.4.3 The ERL Variable 
It is sometimes useful to be able to recognize the line number at which an error occurred. Following an error detection, 
the integer variable ERL contains the line number of the error.’ 


ERL would be used, for example, to indicate which of several INPUT statements caused an END OF FILE error. 
Care must be taken in use of the ERL variable since changing or resequencing the line number field of all or some 


~~, statements within the program can alter the value of the ERL variable as it appears within an expression context. For 
example: 


1 The one exception to this rule is the 7?PROGRAMMABLE CTRL/C TRAP error (ERR = 28) as described in the RST. S/E Programming 


Manual. In this case ERL is not set, but the LINE Variable is set to the line number executing when CTRL/C was typed. 
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_LISTNH 
1LO0 QON ERROR GOTO 1000 
ge Be INFUT “TYFE TWO NON-ZERO NUMBERS’$ Ask 
120 LEY X=A/8 
130 LEY X=X+B/A 
140 FRINT xX 
Lao STOP 
LOGO IF ERR«>61 THEN ON ERROR GOTO O 
LO10 FRINT “FIRST NUMBER WAS 0’ IF ERL=130 
LO20 PRINT “SECOND NUMBER WAS 0% IF ERL=120 
327? END 
Ready 
RUNNE 
TYFE TWO NON-ZERO NUMBERS? S»10 
Foe 


Ston at Lire to 
Pies ap icf yy 

CONT 

Reacts 


KUNNH 
TYPE TWO NON-ZERO NUMBERS? 620 
SECOND NUMBER WAS 0 


Re sci 


RUNNH 
TYFE TWO NON-ZERO NUMBERS? O97 
FIRST NUMBER WAS O 


Re a chy 


If the LET statements in line 120 and 130 were moved to some other line numbers, lines 1010 and 1020 would also 
require a change. 


8.5 IF-THEN-ELSE STATEMENT 
The IF-THEN statement allows the program to transfer control to another line or execute a specified statement depend- 
ing upon a stated condition. 


The IF-THEN-ELSE statement is the same as the IF-THEN statement, except that rather than executing the line follow- 
ing the IF statement, another line number or statement can be specified for execution where the condition is not met. 
The statement is of the form: 


IF <condition> THEN <statement> 


GOTO <dine number> 


THEN <dine number> 
ELSE <statement> 


ELSE <Jine number> ; 
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where the condition is defined as one of the following: 


<relational expression> 
logical expression> 


A relational expression is defined as: 

<expression> <relational operator> <expression> 
as described in Section 3.5. 
A logical expression is one of the following: 

1. An integer expression (FALSE if 0, TRUE if <> 0) 

2. A set of relational expressions, corrected by logical operators 

3. A set of integer expressions, or logical expressions, or both, connected by logical operators. 
The condition is tested; if it is true the THEN/GOTO part of the statement is executed. If the condition is false, the ELSE 
part of the statement is executed, Following the word ELSE is either a statement to be executed or a line number to 
which control is transferred. 
As an example of an IF-THEN-ELSE statement: 

iS IF X>Y THEN FRINT ‘GREATER’ ELSE PRINT ‘NOT GREATER’ 


An IF statement can follow either the THEN or ELSE clause in the above statement, making it possible to nest IF state- 
ment to any desired level. For example: 


L.ISTNH 
100 INFUT “ENTER THREE NUMBERS’ sAsByC 
110 IF ASB THEN 


IF BoC THEN FRINT ’A>B>C 
ELSE IF C>A 
THEN PRINT ‘’C>A2B’ 
ELSE FRINT ’ASC>B’ 
ELSE IF AsC THEN PRINT ’B>A>C/ 
Rice 2 eG 
THEN FRINT ‘BeC>A’ 
ECSE FRINT “CsH>A’ 
bal G7 END 


Re scy 
RUNNEH 
ENTER THREE NUMBERS? 4.49-.019-3.5 
AS BSC 
Ready 
RUNNH 
ENTER THREE NUMBERS? 2005%92.8%3006 
CASE 


Ne chy 
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RUNNH 
ENTER THREE NUMBERS? 3» 24 
CASE 
Reacy 


The use of line continuation and TAB characters greatly improves the legibility of complex program statements such 
as line 110 above. 


The IF-THEN-ELSE statement can appear anywhere in a multiple-statement line. However, if this statement is 
followed by any other statements, the following rules apply: 


1. The physically last THEN or ELSE clause is considered to be followed by the next statement on the line: 


21d IF A=1.0 THEN GOTO 100 ELSE FRINT A \ FRINT “ABNORMAL * 


where A#1, the value of A and the text string ABNORMAL are printed. 
2. All other THEN or ELSE clauses are considered to be followed by the next line of the program: 


20 IF ASB THEN IF BSC THEN PRINT ‘°B«<C’ 
\ GOTO 30 
eae FRINT “AB? 


Only in the case where “B<C” is printed is the statement GOTO 30 seen and executed. If either A<B or 
B>C, the line ““A<B” is printed. 


8.6 CONDITIONAL TERMINATION OF FOR LOOPS 
In the simple FOR-NEXT loop described in Section 3.6.1, the format of the FOR statement is given as: 


FOR <variable> = <expression> TO <expression> STEP <expression> 


There are many situations in which the final value of the loop variable is not known in advance and what is really 

desired is to execute the loop as many times as necessary to satisfy some condition. In evaluating a function, for example, 
this condition might be the point at which further iterations contribute no further accuracy to the result. BASIC-PLUS 
provides a convenient way of specifying that a loop is to be executed until a certain condition is detected or while some 
condition is true. These statements take the forms: 


FOR <variable> = <expression> STEP <expression> WHILE <condition> 
and 

FOR <variable> = <expression> STEP <expression> UNTIL <condition> 
The condition has the same structure as specified in an IF statement (see Section 3.5) and can be just as elaborate, if 
necessary. Before the loop is executed and at each loop iteration the condition is tested. The iteration proceeds if the 
result is true (FOR-WHILE) or false (FOR-UNTIL). 
The difference between a FOR loop specified with a WHILE or UNTIL and one specified with a terminal value for the 


loop variable is worth noting, in order to avoid potential pitfalls in the usage of each. Consider the two loops in the 
program below: 
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LISTNH 
19 FOR I=1 TH 10 
\ PRINT I35 
\ NEAT I 
eae) FRINT “T=’3I 
aL @) FOR I=1 UNTIL Is10 
\ FRINT Is 
\ NEXT I 
450 FRINT ’T#’93I 
o2767 ENT 
Keacdy 
RUNNH 
Pe a SS RF Be OD eA 
5 ect Sees eee ees See See gee: . Sa, eee SS Se yee SI 


Ready 


Each of these loops prints the numbers from 1 to 10. When the loop at line 10 is done, however, the loop variable 
is set to the last value used (that is, 10). In the second loop beginning at line 50, the loop variable is set to the value 
which caused the loop to be terminated (that is, 11). 


Next consider the two loops following: 


LISTNH 


16 X10 
2Q FOR I=1 TO X 
\ X*X/2 
\N PRINT I+X 
\ MEAT £ 
30 FRINT 
\ X=10 
AO FOR I=1 UNTIL I>xX 
\ X=X/2 
\N FRINT IX 
\ NEAT 
Bef O67 ENT 
Reacdy 
RUNNH 
1 a 
2 eo 
3 e235 
4 shew 
a soled 
& 215625 
Z ©O781235 
3 rer? QV62Z0E~-1 
9 219S313E-1 
10 P76S6S3E-2 
1 <a 
a Aes 
Ready 


In the case of the loop 
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beginning with line 20, the iteration stops when I exceeds the initial value of X (that is, 10). - 


Even though the value of X changes within the loop, the initial value of X determines the performance of the loop. In 
the second loop, the current value of X determines when the iteration ceases. Thus, after three iterations, I is greater 
than X in the second loop and the loop is terminated. (The STEP value when omitted, is still assumed to be 1.) 


These forms of loop co 


ntrol are particularly useful in iterative applications where data generated during the loop execu- 


tion determines loop completion. 


Consider the problem of scanning a table of values until two successive elements are both O or the end of the table is 


reached: 


LOG FOR T=] UNTIL T=N OR X¢CT)=0 AND X¢CI+1)=0 


\ NEAT ST 


The following two programs also illustrate the FOR-UNTIL and FOR-WHILE constructions: 


tis TNH 
LOQ 
je 8 
120 


1340 
LAG 
SOO 
3276/7 
Re acy 
RUN NE 


Celi ens 
CETIeR 


Ae 3 chy 
RUNNH 
LETTER I 
IMNFROFER 
Re acy 
RLINNH 
LETTER I 
LETTER I 


Securcae Be 


INPUT “LETTER IS’3 Ys -— 
XS ee 

FOR ITA=O4 UNTIL X$=Y¥% OR X$ = °7777 

\ READ X44 

\ NEXT TK 

Te X# = “222° THEN FRINT “IMPROPER INFUT~’ 

\ GO TO 32767 

PRINT “LETTER IS NUMBER’$I%s ’IN ALPHABET’ 

QATA AvykKeCylvEsF eGety t sy Jy KolheMeyNv Oe Fo Qe Rye Sy Tye VeW ye Xe Vo Ze 277 
ENT 


—_ 
S? J 
S NUMBER 10 IN ALPHABET 
—_— 
S? 9 ; 
INFUT 
S? Xx 
S NUMBER 24 IN ALPHABET : 
— 
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“- RUNAH 
LETTER IS? Cc 
IMPROPER INFUT 
a Re sci 
7 
LISTNH 
L100 INFUT ‘WORD $Y% 
L110 Xda ¢ 
120 FOR I% =O% WHILE X#<=Y¢ 


\ READ X$ 
\ NEAT I2 


_— SOG QATA AvyBeyCyDvEeF es Grete Ty Ie KolLeMeNv Oe Fe Qe Re Se TotivVyWe Xe Vo Ze 277 


140 IF TA = 1A THEN FRINT ‘“IMFPROFER INFUT’ 
\ GO TO 32767 

140 PRINT “WORT BEGINS WITH LETTER’ ¢1%-1% 

32767 ENT 

Ready 

RUNNH 


WORDT SECOND 
WORT BEGINS WITH LETTER 19 


™_-~ Reacty 
RUAN 
WORT? /MESSAGE 
IMFPROFER INFUT 
Re acy 


8.7 STATEMENT MODIFIERS 


yew To increase the flexibility and ease of expression within BASIC-PLUS, five statement modifiers are available (IF, 
UNLESS, FOR, WHILE, and UNTIL). These modifiers are appended to program statements to indicate conditional 


execution of the statements or the creation of implied FOR loops. 


8.7.1 The IF Statement Modifier 
The form 

<statement> IF <condition> 
is analogous to the form: 


IF <condition> THEN <statement> 


For example: 


LOO PRIN 3 fe A Os 
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is the same as: 
1900 IF X22 O.« THEN FRINT X 
The statement is executed only if the condition is true. 


When a statement modifier appears to the right of an IF-THEN statement, then the modifier operates only on the 
THEN clause or the ELSE clause, depending on its placement to the left or right of ELSE. For example: 


100 lf ..i=) THEN PRINIG  -“HELLO”- ELSE PRING *3yk" ITE 2=2 
will print: 

HELLO 
since the test 1=1 is true. The modifier IF 2=2 is also true, but as it applies only to the ELSE clause, it is never tested. 
It is not possible to include an ELSE clause when using the modifier form of IF. 
Several modifiers may be used within the same statement. For example: 

100 PRIN X02 93) 3 1 Er oat eg 9 
prints the value of X(I,J) only if the value of X(I,J) is non-zero and if I equals J. When there is more than one modifier 
on a line, the modifiers are executed in a right-to-left order. That is, the rightmost one is executed first and the leftmost 
is executed last. This situation is described by the term “nested modifiers.” 


An additional operational advantage of IF modifiers is illustrated in the discussion of FOR modifiers in Section 8.7.3. 


8.7.2. The UNLESS Statement Modifier 
The form: 


<statement> UNLESS <condition> 


causes the statement to be executed only if the condition is false. This particular form simplifies the negation of a 
logical condition. For example, the following statements are all equivalent: 


1LO0 FRINT A UNLESS A=0, 

110 FRINT A IF NOT A=0. 

120 IF NOT A=QO. THEN FRINT A 
120 IF A i> QO THEN FRINT A 


8.7.3 The FOR Statement Modifier 
The forms: 


<statement> FOR <variable> = <expression> TO <expression> | STEP <expression> t 


and 


<statement> FOR <variable> = <expression> ‘ STEP <expression>} : WHILE <condition> 


UNTIL <condition> 
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can be used to imply a FOR loop on a single line. For example (using none of the optional elements): 
100 FRINT Ty SQRC¢I) FOR I=1. TO 10. 


This statement is equivalent to the following FOR-NEXT loop: 


100 FOR T=1. TO 10. 
\ PRINT ts SQRCT) 
\- NEAT I 


In cases where the FOR-NEXT loop is extremely simple, the necessity for both a FOR and a NEXT statement is 
eliminated. Notice that this implied FOR loop will only modify (and hence execute iteratively) one statement in 
the program. Any number of implied FOR loops can be used in a single program. 


As in the case with all modifiers, a FOR modifier in an IF statement operates only on the THEN or ELSE clause with 
which it is associated, and never on the conditional expression to the left of the THEN. Thus, if it was desired to print 
all non-zero values in a matrix X(100), the following program would not operate properly: 


10 QIM xX¢€10024) 
1S READ X€I“Z) FOR IT4=1%2 TO 100% 
2 Q IF XCIZ)«£20 THEN PRINT I49xX¢CI4Z)» FOR [4=14 TO 1002 


since the implied FOR loop at line 20 applies only to the THEN PRINT ... part of the statement, and not to the IF... 
part. The first value of X tested is X(100), since I remained at 100 from statement 15. To achieve the desired effect, 
it is only necessary to state line 20, not as an IF statement, but rather as a PRINT statement with nested modifiers; 
for example: 


2Q PRINT I¢%sX(IZ)»9 IF XCIA)SSO FOR IX = 1% TO 100% 


When expressed in the latter form, the nested modifier rule takes effect, and all the values of X(I) are tested and 
printed as appropriate. 


The WHILE and UNTIL clauses are explained in Section 8.6. 


8.7.4 The WHILE Statement Modifier 
The form: 


<statement> WHILE <condition> 

is used to repeatedly execute the statement while the specified condition is true. For example: 
LO LET X#X° 2 WHILE xX 2: <. TES 

is equivalent to: 


LISTNH 10 
190 LET X2#X°2 
Node AS 166 THEN 10 
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The WHILE modifier (and the UNTIL modifier in Section 8.7.5) operates usefully only in iterative loops where the 
logical loop structure modifies the values which determine loop termination. This is a significant departure from FOR -, 
loops, in which the control variable is automatically iterated; a WHILE statement need not have a formal control vari- 


able. The following infinite loops never terminate: 


_— 


10 X=X + | WHILE I=1000 . 

2 Q PRINT I» ACI? WHILE ACD: <> 0 = 
In both cases, the program fails to alter the values which are used to determine when the loop is done. ‘ 
A successful application of the WHILE modifier is shown below: 

LISTNH 

LOG | TEST OF SQUARE ROOT ROUTINE 

L1o X= 1 +¢OXkK24) WHILE X = SQR(X72%) 

L20 PRINT X 

Dasror EE NY 

Ready 

RUNNH = 

4h¢ Lloating roint error at line 110 

eLB4S467E 20 

Re achy 
8.7.5 The UNTIL Statement Modifier 
The form: - 

<statement> UNTIL <condition> 
is used to repeatedly execute the statement until the condition becomes true; which is to say, while the condition is 
false. For example: 

100 Ao) RECA ANG IL X <> SORCES 

\ FRINT X 
-_ 

is the same as: -_ 

100 IF X = SQRCX"224) THEN GO TO 110 ELSE GO TO 130 

L110 Koh tl 

120 GO TO 100 

130 PRINT X 
8.7.6 Multiple Statement Modifiers e 
More than one modifier can be used in a single statement. Multiple modifiers are processed from right to left. For 
example: 

LOO LET ASB IF AsO IF B20 
is equivalent to any of the following: 

- 
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100 TF B2O THEN IF AsO THEN A=B 
or 

LOO IF B:0 AND AsO THEN LET A=B 
or 

100 IF Be=O THEN 150 

L110 IF Aw=Q THEN 150 

120 LET A=K 

130 ! TEST OF A AND B COMPLETE 


A 2-dimensional matrix (m by n) can be read one row at a time as follows: 


LeeLe) READ ACI»yJ) FOR J=1 TO M FOR IT=1 TO N 


which is equivalent to: 


£50 MAT REATIH ACN» M) 
and to: 

Lao FOR I=] TO N 

L40 FOR J=1 TO M 

179 REAL ACI» > 

LEO NEXT a 

LYO NEXT I 


Also see Section 8.7.3 which described the interaction of FOR and IF modifiers. 


8.8 SYSTEM FUNCTIONS AND STATEMENTS 

RSTS/E has several system functions which allow the user to obtain certain information about or perform operations 
with the system. The functions are described in Table 8-1. (Several system functions used frequently in user programs 
are also described in earlier sections.) 


Table 8-1 
System Functions 


Sample Usge 


DATE$ (0%) | Returns the current day, month FRINT DATE$(Q) 
and year, in the form: O7-Nove7& 


22-Mar-76 Re aciy 


Note that the date contains both 
upper and lower case characters 


If the run time system is gener- 
ated with the numeric data 
option, DATES returns the date 
as year.month.day; for example: 


76.03.22 


DATES (N%) 


TIMES (0%) 


TIMES (N%) 
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Table 8-1 (Cont.) 
System Functions 


Returns a character string cor- 
responding to a calendar date. 
The formula used to translate 
between N and the date is as 
follows: 


(day of year) + [(number of 
years since 1970)*1000] 


DATES(1%)=“‘01-Jan-70” 
DATES(2060%)="*29-Feb-72” 


If the run time system is gen- 
erated with the numeric data 
option, DATES return the 
data as year.month.day; for 
example: 


76.02.29 


Returns the current time of 
day as a character string as 
follows: 


TIME(0)=“05:30 PM” 
or “17:30 ” 


Returns a string correspond- 
ing to the time at N minutes 
before midnight. For 
example: 


TIME$(1%)=11:59 PM”’ 
Ore 


TIME$(1440%)="12:00 AM” 
or “00:00 ” 


TIMES$(721%)=“‘11:59 AM” 
or “11:59 ” 


N% must be less than 1441 to 
return a valid string. The 
format of the string (i.e., 
02:40 PM or 14:40) is deter- 
mined at system generation 
time. 


PRINT DATES (6278) 
04-Oct-76 


Ready 


IF TIME$¢(Q) -= 706200 FM’ 
THEN PRINT “OQINNERTIME ’ 


PRINT TIME€ C1) 
Ives ee 


Re scy 


FRINT TIMES C1400) 
12340 AM 


Ready 
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Table 8-1 (Cont.) 
System Functions 


TIME (0%) Returns the clock time in wd IF TIME CO)>43200 

seconds since midnight. | THEN FRINT “AFTERNOON ’ 
TIME (1%) Returns the central processor 19 IF TIME C1)=30 

(CPU) time used for the job in THEN STOPE 

0.1 second quanta. 13 SECONDS ALLOWET 
TIME (2%) Returns the connect time 340 IF TIME C2)21000 THEN STOF 


(time during which the user 
has been logged into the sys- 
tem) for the job in minutes. 


TIME (3%) Returns the number of kilo- 1L8oO FRINT TIME¢3) 
core ticks (KCT’s) used by the 

job. (See the RSTS/E System 

User’s Guide for an explana- 

tion of KCT’s.) 


TIME (4%) Returns the device time for eed IF TIME (4)/6022.35 
the job in minutes. THEN GOTQ %O 
SWAP% (1%) Causes a byte swap operation 500 FRINT CHR# (SWAFPACT A) 


to occur on the integer vari- 
able 1%: returns the value of 
1% with the bytes swapped. 


RADS$(I%) Converts an integer to a 3- 280 FRINT RADG CIA) 
character string. This function 

is used to convert a value 

(expression in Radix-50 for- 

mat) back into ASCII. Radix- 

50 is explained in Appendix 

D of the RSTS/E Program- 

ming Manual. 


There are also two special system statements that can be used within a BASIC-PLUS program: SLEEP and WAIT. Both 
statements allow the user to suspend his program for a stated interval. 


The SLEEP statement is of the form: 
SLEEP <expression> 
SLEEP is used to dismiss the currently running program for the number of seconds indicated by the expression. At the 


end of this period the program is again runnable. Thus, the user is guaranteed at least this number of seconds idle time, 
possibly slightly more depending upon the number of jobs currently active on the system. 
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To awaken a job from a sleep before the specified number of seconds has expired, type a delimiter (RETURN, LINE 
FEED, FORM FEED or ESCAPE) at any of the job’s terminals. The program segment shown below, however, can be 
used to override line terminating delimiters and provide a continuous SLEEP for a specified time. 


100 T=TIME (O> 
L10 SLEEP T+350-TIME (CO) 

\. IF TINE CO)-T<30 GOTO 110 
L2o INFUT xX 


In the above program, the INPUT statement is executed only if the time elapsed is equal to or greater than 30 seconds. 
Otherwise, if a delimiter is typed, the SLEEP is executed again for the length of time remaining in the original 30 
seconds or until another line terminating character is typed. | 


A job is also awakened when it has declared itself a receiver and a message is queued for it through the SEND/RECEIVE 
system function calls. (The SEND/RECEIVE system function calls are documented in the RSTS/E Programming Manual. 


The WAIT statement is of the form: 

WAIT <expression> 
WAIT is used to set a maximum period for the system to wait for input from the user keyboard. If no delimiter is typed 
at the keyboard (RETURN, LINE FEED, ESCAPE) within the number of seconds specified by the expression, the 


program is restarted and a KEYBOARD WAIT EXHAUSTED error (ERR=15) occurs, which can be detected using ON 
ERROR-GOTO. The WAIT statement is used in conjunction with the INPUT statement. As an example: 


L.LSTNH 

10 ON ERROR GOTO 1600 

Fe WAIT 13 

30 INFUT “16 + 16 =’3A 

40 WAIT O 

wQ IF A=32 THEN FRINT “RIGHT! ’ 
ELSE FRINT “NOs TRY AGAIN’ 
ate SERED Bee 

SO S TOF 

100 IF ERR S13 THEN ON ERROR GOTO O 

110 FRINT “WAKE UF!” 

120 RESUME 30 

$2767 ENT 

Ready 

SUNNE 


16 + 16 =? WAKE UF! 
Lé- + 14 =7 $0 

NOy TRY AGAIN 

16 + 16 =f $2 
RIGHT! 

Stor at line 60 


Re acy 
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In this example line 100 is executed only if the user fails to respond within 15 seconds. The use of WAIT 0 restores the 
terminal to its normal state in which no timeout occurs, but rather the system waits until a line is entered, however 
long that may take. 
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PART Ill 


BASIC-PLUS DATA HANDLING 


Part III contains a complete description of all BASIC-PLUS data handling operations. A brief review is made of the 
simple forms of READ, DATA, PRINT, RESTORE and INPUT along with the more advanced forms of these state- 
ments. Formatted ASCII files, virtual core matrices, and record I/O operations are described. 


Advanced users are advised to consult the RSTS/E Programming Manual for a description of advanced data handling 
techniques and device dependent operations. 


Ke 
Oe 


+ 


iy : 


1) Mp 


CHAPTER 9 
DATA STORAGE CAPABILITIES 


9.1 FILE STORAGE 

Previous chapters have described techniques for entering data into a program as the program is written (via READ and 
DATA statements) or from the user terminal while the program is executing (via the INPUT statement). Either tech- 
nique is inefficient when more than a few items are to be read or written. Thus BASIC-PLUS also provides facilities 
to define and manipulate permanent data files. 


A BASIC-PLUS data file consists of a sequence of data items transmitted between a BASIC program and an external 
input/output device. The external device can be the user terminal, some other terminal, disk, line printer, card reader, 
magnetic tape device, DECtape, or high-speed paper tape equipment. 


Each data file and device has both an external name by which it is identified within the RSTS/E system (the name of the 
file on a disk storage device, for example) and a channel number used to reference the file. An OPEN statement asso- 
ciates and external file specification with an internal file channel. 


This chapter describes briefly the key concepts and terminology of data storage as it concerns a BASIC-PLUS user. More 
detailed information is available in the RSTS/E Programming Manual and the RSTS/E System User’s Guide. 


9.2 OPEN STATEMENT 

The OPEN statement associates a file on a file-structured device or some non-file structured device with an I/O channel 
number internal to the BASIC program. (The I/O channel is a logical entity, having no relationship to a hardware 
channel.) BASIC-PLUS permits up to 12 files to be open at a given time. Channel numbers 1% to 12% specify device 
channels, and channel number 0% specifies the user’s terminal. 


The general form of the OPEN statement is as follows: 


OPEN <string> aa nee 


FOR ee AS FILE <expression> 


The string field is a character string constant, variable or expression that contains a filename. It can also contain a device 
designation (logical or physical), a project-programmer code, a file extension specifying the file type, and a protection 
code; these optional fields are described in the RSTS/E System User’s Guide. After opening a file or device, the program 
performs input and output by referring to the channel number, as indicated by the expression following the key word 
FILE. The expression must be an integer in the range | to 12. 


Protection codes are normally specified only in the NAME-AS statement, which changes the name and protection code 
of an existing file (see Section 9.4). However, protection codes can be specified as an optional part of any filename. 
For example. 


3530 OPEN “’FILE.-EXT<40>° FOR INFUT AS FILE 124 


The file FILE.EXT is created under the current account with a protection code of <40>. The AS FILE expression cor- 
responds to the internal channel number on which the file is being opened; channel | in this case. 
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One or more of the following specifications can be appended to the end of the statement. They are described in 
Sections 9.2.1 through 9.2.4. 


|,RECORDSIZE <expression>} — |,CLUSTERSIZE <expression>} 
| FILESIZE <expression>} 1 MODE <expression>} 

Options must be in the exact order shown. If options are out of order, the message 
?MODIFIER ERROR 


appears. Omitting an option is equivalent to specifying that option with a parameter of 0% except for the MODE 
option on non-file-structured magtape. 


There are three distinct forms for the OPEN command: 


OPEN <string> FOR INPUT 
OPEN <string> FOR OUTPUT 
OPEN <string> 


The form of the OPEN statement used determines whether an existing file is to be opened or a new file created. 


1. An OPEN FOR INPUT statement causes a search for an existing file (since the statement indicates the 
file is an input file). If no file is found, the CAN’T FIND FILE OR ACCOUNT error (ERR=S) occurs. 


120 OPEN. “FILE. DAT”. FOR INPUT AS PILe 22 


2. An OPEN FOR OUTPUT statement causes a search for an existing file which, if found, is deleted. A new 
file is then created. 


2 /Q OREN “DATA.O1240>° FOR OQUTFUT AS FILE 32% 


3. An OPEN statement without an INPUT or OUTPUT designation attempts to perform an OPEN FOR 
INPUT operation as described above. If this fails, a new file is created. 


160 OPEN ‘MATR.TER’ AS FILE 772A 


The OPEN statement does not control whether the program attempts to perform input or output on the disk file or 
whether read and/or write access to the file is granted’; these privileges are controlled by the file protection code and 
MODE value. 


If, for some reason, the program cannot gain access to the file or device, an error is returned. Table 9-1 summarizes 
some of the more common errors that occur on attempted file access. 


: Magtape and DECtape are exceptions to this rule. See the RS TS/E System Programming Manual. 
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ERR 
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?Bad directory for device 


?Tlegal file name 


No room for user on device 


?Can’t find file or account 


Not a valid device 


?Device not available 


?Protection violation 


?Device hung or write locked 


?Too many open files on unit 


?No buffer space available 


?Magtape select error 


Illegal I/O channel 


Table 9-1 
Open Statement Errors 
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The directory of the referenced device is in an unread- 
able or illegal format. 


The filename specified is not acceptable. It contains 
unacceptable characters or the filename specification 
format has been violated. 


Directory space for the current user of the specified 
device has been exceeded, or the device as a whole is 
too full to accept further data. 


The file or account number was not found on the 
specified device. 


The device specification supplied is not valid for one 
of the following reasons: 


1. Either the unit number or its type is not in 
the system configuration. 

2. The logical name has no associated physical 
device and is thus untranslatable. 


The specified device exists on the system but a user’s 
attempt to ASSIGN or OPEN it is prohibited for one 
of the following reasons: 


1. The device is currently reserved by another job. 
2. The user lacks necessary access privileges for 
the device. 
. The device is disabled. 
. The device is a keyboard line for pseudo- 
keyboard use only. 


The user does not have the necessary access privileges 
for the file. 


User should check hardware condition of device 
requested. Possible causes of this error include a line 
printer out of paper or a high-speed reader being 
off-line. 


Only one open DECtape output file is permitted per 
DECtape drive. Only one open file per magtape drive 
is permitted. 


The user accessed a file and the monitor requires one 
small buffer to complete the request. No small buffer 
is currently available. 


When access to a magtape drive was attempted, the 
selected unit was found to be off-line. 


An I/O channel number was specified outside the range 
of integers 1 through 12. 
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When used with disk files, an OPEN FOR INPUT or OPEN FOR OUTPUT allows either read or write operations on the 
opened file. The system allows write access to a file if the protection code permits and if no other user has write access 
to the file. For example, if user 1 opens a file, he has read and write access. When user 2 opens the same file, he has 

read access only;a PROTECTION VIOLATION error occurs when he attempts to write on that file. When user 1 sub- 
sequently closes the file, no user has write access until the next open operation. User 3 can now open the file and obtain 
both read and write access, because no other user currently has write access to that file. On DECtape and magnetic tape 
devices, the FOR INPUT and FOR OUTPUT clauses restrict operations on that file to the type of operation specified. 


NOTE 
Only one user can have write access to a file at a time 
unless MODE 1% (that is, update mode) is used for 
disk files. 


The next four sections in this manual describe generally the RECORDSIZE, CLUSTERSIZE, FILESIZE and MODE 
options of the OPEN statement. See the RSTS/E Programming Manual for device-dependent details. As these are 
sophisticated file-handling tools, it is suggested that the novice user initially skip these sections and continue with 
Section 9.2.5. 


9.2.1 RECORDSIZE Option 

When any file is opened, the system creates a buffer area in the user’s memory space to buffer all I/O to and from the 
file. Normally the amount of space reserved is determined by the device, because each device has a default device 
buffer size as described in Table 9-2. 


Table 9-2 
Default Device Buffer Size 


Default Device Buffer Size 
(in characters or bytes) 


All disks 
Floppy disk 
DECtape 


Magtape (DOS or ANSI) 
High-speed reader 
High-speed punch 

Line printer 

Card reader 

User terminal 


The default buffer size may differ when the device is used as a non-file structured device. 


*For ANSI magtape, the system reads a value from the header label to establish the buffer size. 


With the RECORDSIZE option, the user program can allocate more buffer space than is provided by the default case. 
However, in some cases the particular device driver may not permit additional space to be used. 


The buffer size must be an even number. If odd, BASIC uses the next lower integer. To learn the size of the buffer on 
any channel n, the user can invoke the BUFSIZ function. Table 9-3 shows the buffer size alterations for specific devices. 
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Table 9-3 
Use of RECORDSIZE 
Possible Buffer Alterations 


Disk The disk drivers permit use of any buffer size that is an integral multiple of 


512 bytes. 


The DECtape driver uses only the first 510 bytes of the available buffer space 
(512 bytes for non-file structured DECtape). 


DECtape 


Magtape (DOS or ANSI) The magtape driver uses only enough bytes for one physical magtape record. Each 


physical record must be at least 14 bytes, and be no larger than the buffer size. 


High-speed reader 
High-speed punch 
Line printer 

User Terminal 


These non-file structured devices can use any selected buffer size greater than the 
default size. 


Card reader The card reader driver uses only enough bytes for one card’s data. 


Floppy disk The floppy disk driver permits use of any buffer size that is an integral multiple of 


128 bytes. 


The RECORDSIZE option has significant advantages when used with magtape and disk files. On a disk file, total 
throughput can be improved by using a larger buffer size, as this permits a single disk transfer to read a large quantity 
of data. Specify only an even nuniber of bytes in the RECORDSIZE expression. For example: 


100 OPEN “MASTER.DAT’ FOR INFUT AS FILE 14% RECORDSTIZE 2048% 


If the file MASTER.DAT were on an RF11 disk and occupied a contiguous area on that disk, a 2048-byte transfer would 
take about 33ms while four 512-byte transfers would take about 83ms (on the average). If the file did not reside in a 
contiguous disk area, the RSTS Monitor would break the 2048-byte transfer into four 512-byte transfers. Even in this 
last case, the system overhead to perform the transfer would be less. 


This example raises the question of how to ensure that a file occupies a contiguous disk area. This can be done by means 
of the MODE option (see the RSTS/E Programming Muiual) or the CLUSTERSIZE option described in the following 
section. 


BASIC-PLUS establishes the default buffer size when a value less than the default is given. To obtain a buffer size that 
is less than the default, specify the desired buffer size, plus 32767%, plus 1%. Smaller buffer sizes are often useful when 
performing I/O operations on alternate channels. 


Thus, to open the paper-tape reader with a buffer size of two bytes for use with alternate channel I/O, write 


OPEN “PP:” FOR INPUT AS FILE 1%, 
RECORDSIZE 32767% + 1% + 2% 


9.2.2 CLUSTERSIZE Option 
The CLUSTERSIZE option applies only to disk and ANSI magtape files created with an OPEN or OPEN FOR OUTPUT 
statement. The CLUSTERSIZE specification is ignored in all other cases. 


The following description applies to disk files. CLUSTERSIZE is also legal for ANSI magtape. See the RSTS/E 
Programming Manual for further information. 
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The RSTS system divides each disk into a number of 256-word blocks. Each block is assigned a unique logical block -~ 
number starting at 1.’ Logical block numbers are assigned such that block n is physically contiguous with blocks 
n+landn- 1. _ 


A number of contiguous blocks taken together as a unit are called a cluster. RSTS permits clusters to be 1, 2, 4, 8, 16, 
32, 64, 128 or 256 blocks long. When the disk is initialized (the process by which the disk is cleared for use on RSTS), “= 
a minimum cluster size can be established. This minimum cluster size (called the pack cluster size) for the disk can be 
1, 2,4, 8, or 16 blocks. 


For each file on the system, an entry is made in the owner’s file directory (User File Directory or UFD) containing the 
retrieval information for the file: filename, cluster size for the file, and a sequential list of clusters belonging to that 
file. 


A UED has a fixed maximum size which is determined when the UFD is created.2, A UFD on any one disk cannot 
exceed 112 (decimal) blocks (28,672 words). If all files were a minimum size (7 or fewer clusters long) a UFD 
clustered as 16 would have room for a maximum of 1157 files. To keep the list of blocks belonging to the file as short 
as possible, the UFD contains a 1-word entry for the first block of each cluster. Knowing the first block number of the 
cluster and the cluster size is sufficient to determine all of the blocks in the cluster. - 


Because of the size limit on the UFD, large files benefit from the specification of large cluster sizes. In an extreme exam- 
ple, the UFD would be completely filled by a single file of 24,283 blocks where the file cluster size is one block. How- 
ever, with a cluster size of 256 blocks, only 128 words of the UFD are required to describe this file. 


Since most user files are not extremely large, omitting the CLUSTERSIZE option when creating the file makes little 
practical difference. Omitting the CLUSTERSIZE option is equivalent to specifying CLUSTERSIZE 0% and has the 
effect of assigning a cluster size equal to the pack cluster size for the disk on which the file resides. An attempt to 

create a file with a cluster size less than the pack cluster size or not a power of 2 causes the ILLEGAL CLUSTER SIZE - 
error message (ERR=23). 


A negative cluster size may be used; this suppresses the ILLEGAL CLUSTER SIZE error when the program uses a 
scratch disk whose maximum cluster size is not known. If the cluster size is negative, the system attempts to create the 
file at the absolute value of the specified cluster size or at the pack cluster size, whichever is larger. 


Once a file is opened on an internal I/O channel, all I/O requests by the BASIC program are handled by means of a read 
or write call from BASIC-PLUS to the Monitor, directed to the nth virtual block of the file. The RSTS system trans- 
lates the virtual block number into a logical block number. This is done by reading the file’s retrieval information and - 
finding the entry corresponding to the nth virtual block. To minimize the overhead involved in reading the UFD, which 
is stored on the disk, part of this list of clusters belonging to a file is kept in memory. This part of the list is called 

the file window. The file window is composed of seven entries from the list of file clusters. Since each entry corres- 
ponds to one cluster of the file, with a file cluster size of one. block, seven blocks (or 3584 bytes) of the file are 
described by the in-memory file window. These seven blocks can then be read or written without accessing the complete 
list from the UFD stored on the disk. Similarly, with a file cluster size of 256 blocks, the file window describes the 
location of 1792 blocks of the file, or over 900,000 bytes. When performing random access I/O to virtual memory 
arrays and RECORD 1/0 files, any of the 1792 blocks would be read or written without referencing the UFD. 


1 Block 0 of each disk is reserved for a bootstrap record and is not used by any file. 
The maximum size of a UFD is seven times the cluster size for that UFD, which is established when the account is created, and may be 
1, 2,4, 8 or 16 blocks. The figures given in the text assume a UFD cluster size of 16. 
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As an example of the use of the CLUSTERSIZE option: 


100 OREN “MAT.«UAT’ FOR OUTFUT AS FILE 14% CLUSTERSIZE 128% 


In this case the file MAT.DAT is created with a cluster size of 128 blocks. Note that the file is initially 0 blocks long 
and is extended as needed in 128-block increments. 


Since files with large cluster sizes must be extended by a whole cluster at a time and since clusters are always contiguous 
blocks, it may not always be possible to find sufficient contiguous free blocks to extend the file. If not, the NO ROOM 
FOR USER ON DEVICE error message is printed (ERR=4). The user should be aware of this possibility whenever he 
creates a file with a cluster size larger than the pack cluster size (the minimum cluster size for that disk). 


As another example (using line continuation as described previously): 


LOO OREN “DATA’ FOR OUTFUT AS FILE Ae 
RECORUSIZE 204824» 
CLUSTERSIZE 42% 


The RECORDSIZE option improves disk throughput when multiple blocks can be read or written in a single transfer 
(see Section 9.2.1). By creating the file with a cluster size of 4 (2048 bytes per cluster) the user guarantees that virtual 
blocks 1—4, 5—8, etc., of his file are physically contiguous on the disk. 


9.2.3 FILESIZE Option 
A disk file (and only a disk file) can be pre-extended by using the FILESIZE option in an OPEN statement, eliminating 
the need for a PUT statement. The format for the FILESIZE option is: 


OPEN <string> [FOR OUTPUT] AS FILE <expr> , FILESIZE <expr> 
For example: 

LO0 OPEN “VALUES’ FOR OUTPUT AS FILE 324+ FILESIZE 50% 
The data file, VALUES is opened and automatically pre-extended to 50 256-word blocks. 


FILESIZE is also used on ANSI magtape, but for a different purpose than described above. See the RSTS/E Program- 
ming Manual for further information. 


9.2.4 MODE Option 
The OPEN statement allows another option: the MODE field. The format of the OPEN statement, including the MODE 
field, is as follows: 


OPEN <string> foe ae FILE <expr> 


,RECORDSIZE <expr>} 
,CLUSTERSIZE <expr>} 
MODE <expr>} 


The MODE option is used to establish device-dependent properties of the file. See the RSTS/E Programming Manual 
for device-dependent features. 
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9.2.5 File-Structured Vs. Non-File-Structured Devices 

RSTS/E distinguishes between file-structured (disk, DECtape and magtape) devices and non-file-structured devices. 
When a file is to be found or created on a file-structured device, the file specification string in the OPEN statement 
must include both a device designation (or default public structure) and a filename. On non-file-structured devices, 
the device name alone identifies a file (filename and extension, if specified, are ignored). For example: 


DT0: Insufficient information to specify a file. 
DTO:FRED Specifies the file FRED on DECtape unit 0. 
PP: Uniquely specifies the high-speed punch. 
PPFiLe Same effect as PP:; the filename is ignored. 
DX1: Uniquely specifies floppy disk unit 1. 


File specification syntax is such that the default device (the public disk storage area) need not be specified. 
It is also possible to open a file-structured device in non-file-structured mode. For example: 
160 OPER “DR 2%:* AS FILES 


is sufficient to open a disk cartridge in non-file-structured mode. Device-dependent features are described in the 
RSTS/E Programming Manual. 


9.3 CLOSE STATEMENT 

The CLOSE statement is used to terminate I/O between the BASIC program and a peripheral device. Once a file has 
been closed, it can be reopened for reading or writing on any internal file designator. On a CLOSE the system reclaims 
buffer space assigned to the file. 


All files must be closed before the end of program execution. Execution of a CHAIN statement automatically closes 
any open files, but does not cause the output of the last blocks to output files. (The CHAIN statement is described in 
Section 9.6.) The format of the CLOSE statement is as follows. 


CLOSE <expression> { , <expression>... ' 
The expression indicated has the same value as the expression in an OPEN statement and indicates the internal channel 


number of the file to close. Any number of files can be closed with a single CLOSE statement; if more than one file is 
to be closed, the expressions are separated by commas. For example: 


240 CLOSE 1024 
20 CLOSE 229424 


Line 250 above closes the files opened on internal I/O channels 2 and 4. Line 240 closes the file open on internal I/O 
channel 10. 


9.4 NAME-AS STATEMENT, FILE PROTECTION AND RENAMING 
The NAME-AS statement is used to rename and/or assign protection codes to a disk or DECtape file, and can only be 
used on a given file by someone logged into the system under an account number that has write privilege for that 


file. The format of the statement is as follows: 


NAME <string> AS <string> 
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The specified file (the first string indicated) is renamed (as the second string indicated). When the file resides on a 
device other than the default device (system disk), the device must be specified in the first string and may optionally 
be specified in the second string. No filename extension assumptions are made by NAME-AS; the filename extension 
must be specified in both strings if any extension is present in the old filename or desired in the new filename. For 
example: 


ea NAME “’DTO?OLD.BAS’ AS “NEW. BAS’ 
This is equivalent to: 

L110 NAME “DTOOLT. BAS’ AS “NTOSNEW. BAS“ 
However, the statement: 

190 NAME “FILEL.BAS’ AS “FILE2’ 
is not advised because FILE2 has no extension for automatic recognition by the system. 
A file protection code can be specified within typed angle brackets as part of the second <string> although it is not 
required. If a new file protection code is specified, it is reflected in the protection assigned to the renamed file. If no 
new protection code is specified, the old protection code is retained. See the RSTS/E System User’s Guide for a com- 
plete description of protection codes. 
The statement: 

ZOO NAME ‘“FILE.-EXT’ AS ‘’FILE-«EXT=40>° 
changes only the protection code of the file FILE.EXT stored on the system disk. 
The statement: 

ZOO NAME “NTOsABC.BAS’ AS “XYZ.BAS’ 
changes the name of the file ABC.BAS on DECtape unit 0. Since no transfer of the file from one device to another can 
be performed with the NAME-AS statement, it is not necessary to mention DTO: twice; that is, the device of the new 
filename need not be specified. However, an error is generated if a device other than the old device is specified. 

120 NAME ‘NEW’ AS “NEWI’ 


changes only the name of the disk file NEW. 


9.5 KILL STATEMENT 
The KILL statement is of the form: 


KILL <string> 
and causes the file-named string to be deleted from the user’s file area. (The file can no longer be opened, but if it is 
already open the file remains available until it is closed.) For example, when the user has completed all work with the 


file XYZ (note that the filename has no extension) on the system disk, he could remove the file from storage by 
executing the following statement: 


4&0 32 5 ES Gr es 
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A user is not allowed to KILL a file is write-protected against him. -, 


9.6 CHAIN STATEMENT 

If a user program is too large to be loaded into memory and run in one operation, the user can segment the program 
into two or more separate programs. Such programs are called into core for execution by means of a CHAIN state- 
ment. Each program section is assigned a name and control can be transferred between any two programs. A CHAIN 
statement is of the form: 


CHAIN <string> \<line number>} 


and causes the program named by the string to be called, compiled (if necessary), and executed. The line number, if 
specified, designates the line at which the program is to be started. If the line number is omitted, the program is started 
at the lowest numbered line (as though a RUN command has been used). The CHAIN statement is the last statement 
executed in each program segment (except the last segment). For example: 


1O00 CHAIN ’MAIN.BAC’ 2000 
causes the program MAIN.BAC to be loaded, beginning execution at line 2000. 


Notice that a filename extension is not required. The compiled form of the program is searched for and, if found, run. 
If the compiled form is not found, the non-compiled form is searched for and, if found, compiled and run. If neither 
form of the program is found, an error occurs. 


On the other hand, if a filename extension is specified, and not found, an error occurs; in this case, no other form of 
the program is searched for. 


NOTE o- 
If a CHAIN statement in a nonprivileged program names a _ 
privileged program, the CHAIN statement should not include 
a line number. The entire chained program must be execu- 
ted, or the system will not retain the chained program’s 
privileges. 


Chaining to precompiled program files (.BAC files) is considerably more efficient than chaining to BASIC source 
program files since .BAS files require compilation upon each call. 


Communication between chained programs is performed by means of user’s files or memory common. 


When the CHAIN statement is executed, all open files for the current program are closed, the new program segment 
is loaded, and execution continues. Any files to be used in common by several programs should be opened in each 
program. | 


The CHAIN statement implicitly closes all open I/O channels, which is slightly different from the actions performed as 

a result of a CLOSE statement. For example, the line printer drivers perform two page ejects when the line printer is F 
closed with a CLOSE statement. To continue printing on the same piece of paper after chaining, do not direct a 

CLOSE statement to the line printer channel. The CHAIN statement is sufficient to close the printer without unwanted 

page ejects. 9 
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CHAIN does a fast close on all open files in the chaining program. This saves the data in the file, but any partially filled 
output buffer or modified virtual array elements may be lost. Thus it is generally good programming practice to include 
an explicit CLOSE statement in the program for all open files before chaining or exiting. 


Similarly, an explicit close of the paper tape punch causes a trailer to be punched; the implicit close does not. 


When a program is entered via a CHAIN statement, the STATUS variable is set. For more information see the RSTS/E 
Programming Manual. 


Wann 
} 
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CHAPTER 10 
BASIC-PLUS INPUT AND OUTPUT OPERATIONS 


10.1 READ AND DATA STATEMENTS 
A READ statement is used to assign to a list of variables values obtained from a data pool composed of one or more 
DATA statements. The two statements are of the form: 


READ <iist of variables> 
DATA <dist of values> 


The list of variables can include floating-point, integer, subscripted, or character string variables. Data values must cor- 
respond in type with their respective variables, but the % character should not be included in integer values. Integer and 
floating-point values are interchangeable, although they are stored according to the type of the variable. The use of 
quote marks is discussed below. 


The data pool consists of all DATA statements in a program. Values are read starting with the DATA statement having 
the lowest line number and continuing to the next higher, etc. The location of DATA statements in a program is 
irrelevant, although for simplicity they are usually kept together toward the end of the program. (The DATA statements 
must occur in the proper numeric sequence, however.) A DATA statement must be the last or only statement on a line, 
although a READ statement can occur anywhere on a line. Comments are not permitted at the end of a DATA state- 
ment. If a READ statement is unable to obtain further data from the data pool, an error message is printed and program 
execution is terminated. (This error can be treated through the ON ERROR GOTO statement, Section 8.4.) 


Quotes are necessary in DATA statements only around string items that contain a comma, significant spaces or tabs, or 
lower-case letters that are to be preserved. The data pool, composed of values from the program’s DATA statements, is 
stored internally as an ASCII string list. When a numeric variable is read, the appropriate ASCII to numeric conversions 
are performed. When a string variable is read, the string is used as it appears in the DATA statement. If the item does 
not appear in quotes, then spaces and tabs in the string are ignored. If the item appears in quotes, the string variable is 
equated to the entire string within the quotes. 


Matrices are read from DATA statements via the MAT READ statement of the form: 
MAT READ <matrix> 
This reads the value of each element of a predimensioned matrix from the data pool. Each element in the list of 


matrices indicates the maximum dimension of the matrix to be read (which cannot be greater than the dimensioned size 
of the matrix). Individual elements are separated by commas. For example: 


1900 NIM AC20920)»9 BCSO) 
110 MAT READ A 
120 MAT READ BC3S) 


The above lines read values for the 20-by-20 matrix A and 35 out of the possible 50 values for the B matrix (remaining 
elements are 0). Data is read row by row; that is, the second subscript varies most rapidly. 


10.2 RESTORE STATEMENT 

The RESTORE statement reinitializes the data pool of the program’s DATA statements. This makes it possible to 
recycle through the DATA statements beginning with the lowest numbered DATA statement. The RESTORE statement 
is of the form: 


RESTORE 
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For example: 
aew RESTORE 


causes the next READ statement encountered after executing line 85 to begin reading data from the first DATA state- . 
ment in the program, regardless of where the last data value was found. See Section 3.3.1 for an example program using 
the RESTORE statement. 


The RESTORE statement can be placed in any position on a multiple-statement line. 


10.3 PRINT STATEMENT 
In its simplest form, the PRINT statement: 


PRINT 
causes a carriage return/line feed to be performed on the user terminal. The format: 
PRINT <list> 


causes the printing of the elements in the list on the user terminal. An element in the list can be any legal expression. 
When an element is not a simple variable or constant, the expression is evaluated before a value is printed. The list can 
also contain character strings between quotes which are printed exactly as typed between quotes. 


NOTE 
If a character string is enclosed in a PRINT statement with 
an initial quote and no terminating quote, a terminating -~ 
quote is considered to follow the last character of that PRINT 
statement’s terminal line (up to the carriage return, line feed, 
form feed, or escape character). For example: 


19 FRINT “NAME IS At 
10 FRINT "NAME IS Ag" 
2d FRINT “NAME IS “ As 


Line 10 is shown in two equivalent forms. Line 20 is the correct 
form to generate the printed line: 


NANE IS JOHN DOE 
where A$ = “JOHN DOE”’. 
Elements in the list are separated by commas or semicolons. For example: 


100 AA = 1A 
\ BA = 22 
\ “Basan 

110 PRINT Acs AA + BA + Ch» CH - Ads ‘ENT’ 


when executed causes the following line to be printed: 


= 6 2 END 
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A terminal line is considered to be divided into print zones’ of 14 spaces each. Use of these zones involves the comma 
character which causes the print head to move to the next available print zone (from | to 14 spaces away). If the right- 
most print zone on a line is filled, the print head moves to the first print zone on the next line. 


The semicolon character functions as follows: 


1. If an integer or floating-point variable, function, or expression is followed by a semicolon, the value is 
printed with a preceding minus sign if the number is negative, or a preceding space if it is positive. The num- 
ber is then followed by a single space. 

2. Character strings and string variables followed by a semicolon are printed with no preceding or trailing 
spaces. 


Any PRINT statement which does not end with a semicolon or comma character causes a skip to the next line after 
printing the elements in the list. The presence of the punctuation character at the end of the PRINT list causes the 
next PRINT statement to continue on the same line under the conditions already defined. 


In general, the output rules for the PRINT statement are: 


1. Leading 0’s and trailing 0’s to the right of a decimal point are suppressed. Where a number can be repre- 
sented as an integer, printing of the decimal point is also suppressed. 

2. At most six significant digits are printed, unless the PRINT-USING statement is used. 

3. Most numbers are printed in decimal format. Numbers too large or too small to be printed in decimal format 
are printed in exponential format. 

4. Character string constants are printed without leading or trailing spaces. 

. Extra commas cause print zones to be skipped. 

6. Semicolons separating character string constants from other list items are optional; omitting punctuation 
has no effect on the output format in this case. 


N 


10.3.1 Formatted ASCII I/O 
BASIC-PLUS permits access to data files by three methods: 


1. Formatted ASCII 
2. Virtual memory arrays, described in Chapter 11 
3. Record I/O, described in Chapter 12 


Formatted ASCII data files are the simplest method of data storage, involving a logical extension of the PRINT and 
INPUT statements to be used in conjunction with the OPEN statement. 


The formats for INPUT and PRINT statements to be used with the OPEN statement are: 


line number INPUT #<expression>,<list> 
line number PRINT #<expression>,<list> 


where the expression has the same value as the expression in the OPEN statement (the internal file designator) and the 
list is a list of variable names, expressions, or constants as explained in the sections describing the PRINT and INPUT 
statements. 


1 The actual number of print zones is INT (n/14), where n is the size of the print line. 
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10.3.2 Output to Non-Terminal Devices 
In order to direct output to a device other than the user terminal, the PRINT command is formatted as follows: 


PRINT #<expression>,<list> 
where the expression is the internal channel number (the internal file designator) of a previously opened output file 
(see Section 9.2). The list of information to be output can include any of the output information described as applicable 


to the PRINT statement. For example: 


190 OFEN ‘’DATAL’ FOR OUTFUT AS FILE 72 
110 PRINT #7%% “START OF DATA FILE" 


The above lines open a file called DATAI on the disk with internal channel number 7 (of 12 possible open files avail- 
able to the user). The first line in that file reads: START OF DATA FILE. 


To output a table of square roots on the line printer, the following program could be used: 


LISTNH 
100 LET I¢=’LF? ’ 
\ OFEN 1% FOR OUTPUT AS FILE 124 
+4) PRINT #1242 Is SQRCI) FOR I= 1. TO S- 
32/6/ ENX 
Re aechy 
RUNNH 
Re acy 


PRINT Ivy SQRCI) FOR T=1,. TO 5. 


L 1 

2 1.41421 
3 1.73205 
4 2 

= 22025607 
Ready 


The user terminal can be addressed by referring to channel 0, or by associating a filename with the keyboard, as shown 
in the following two examples. 


LISTNH 
100 PRINT #049 “TEXT” 


Re sci 


RUNNH 
TEAT 


Re acy 


10-4 


BASIC-PLUS Input and Output Operations 


L.ISTNH 
190 OFEN ‘KE?’ AS FILE 12 
\ PRINE 4125“ TEA’ 


Ready 
RUNNH 
TEXT 

Reaecy 


10.3.3 PRINT-USING Statement 
In order to perform formatted output, the following statement is used: 


PRINT {#<expression>,}USING<string>,<list> 


where the expression (which is optional) indicates the internal channel number of the file or device which is the desti- 
nation of the output; the string is either a string constant, string variable, or string expression which is an exact image 
of the line to be printed. This string is called a format field. The list is a list of items to be printed in the format 
specified by the format field. All characters in the string are printed as they appear except for the special formatting 
characters and character combinations described on the following pages. The string, or portions of the string, are 
repeated until the list is exhausted. The string is constructed according to the following rules. 


10.3.3.1 Exclamation Point — An exclamation point in the format field identifies a 1-character string field. The 
variable string is specified in the <list> within the PRINT statement. For example: 


LISTNH 
100 PRINT USING ‘I! !‘» ‘ABs ‘CDs ‘EF? 
32767 ENT 


Ready 


RUNNH 
ACE 


Ready 


The first character from each of the three string constants or variables is printed. Any other characters beyond the first 
are ignored. 


10.3.3.2 String Field — A variable string field of two or more characters is indicated in the format field by spaces 
enclosed between backslashes. The backslash character (\) is produced by typing SHIFT/L on some keyboards. 


Enclosing no spaces indicates a field two columns wide, one space is equivalent to a field three columns wide, etc. 
For example: 


100 PRINT USING “\\\ N¢fv “ABCD ’s “EFGHI ’ 
causes 


AREF GH 
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to be printed at the user’s terminal. The first two backslashes have no spaces enclosed, hence permit the printing of two 
characters (AB). The second two backslashes enclose two spaces and permit the printing of four characters (EFGH). No 
spaces are printed unless specifically planned. 


10.3.3.3 Numeric Field — Numeric fields are indicated with the # character in the format field. Any decimal point 
arrangement can be specified and rounding is performed as necessary (not truncation). For example: 


LOG FRINT USING ‘°#4. ERS 12.3545 
causes 
1245355 


to be printed on the user’s terminal. Also consider the following: 


LOO PRINT USING “#4 sy Le. 345 
L116 FRINT USING /#44#E. oy 12.345 
120 FRINT USING ‘##%r 100 
RUNNH 

$905: 
A. 400 
Reach 


Numeric fields are right justified; that is, if a number does not fill the allotted space, leading blanks precede the number. 
When the field specified is too small for a constant or variable to be printed, the % character is printed to indicate the 
error. The number is then printed without reference to the format field. On the other hand, when the format field 
specified is more than 20 character spaces larger than required for a constant or variable to be printed, a PRINT-USING 
BUFFER OVERFLOW non-recoverable error may occur. 


If the format field specifies a digit as preceding the decimal point, at least one digit is always output before the decimal 
point. If necessary, that digit is 0. 


10.3.3.4 Asterisks — If a numeric field designation in the format field begins with **, any unused spaces in the format 
field are filled with asterisks. For example: 


LOO AZ27 69S 
\ Be107.50 
\ C=1007.50 
\ PRINT USING ‘XX##. #4’ Ay Rel 
RUNNH 
KK 7 49S 
K1L07 450 
LOO? 440 


Re acy 
Notice that the ** characters act as two additional # characters as well as allowing asterisk fill. 


Exponential format (see below) cannot be used in a field with leading asterisks. Negative numbers cannot be output 
using asterisk fill unless the sign is output following the number (see below). 
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mt 10.3.3.5 Exponential Format — When the exponential form of a number is desired, the numeric format field is followed 
by the string (four characters) which allocates space for E-xx. Any arrangement of decimal points is permitted. For 
example: 


LISTNH 


LOO Fas 7 fee AE AR AB EE * 
L110 A=1L0000. 
* L20 FRINT USING FesAvA 
Ready 
RUNNH 
LOE O8 10000 
Ready 
All format positions are used to output a number with an exponent. The significant digits are left justified and the 
a exponent is adjusted. 
10.3.3.6 Trailing Minus Sign — If a numeric format field designation is terminated with a minus sign, the sign of the 
output number is printed following the number, rather than preceding it. A blank is printed to indicate a positive 
number. For example: 
LISTNH 
LOO AB—100% 
L110 PRINT USING ¢#4.44-~- £444.44’ AvA 
a 
Ready 
RUNNH 
$0.00-—. 10.50 
Ready 


Note that if the trailing minus is not used, space must be reserved in the numeric format field for the sign to precede 
the number. 


10.3.3.7 Dollar Signs — If a numeric format field begins with $$, a dollar sign is printed immediately preceding the first 
digit of the number. For example: 


.ISTNH 
100 A=7 7.44 
\ Be 304.55 
: \ C=2211.40 
110 FRINT USING ‘$44.44’, Av Bel 


s Re scy 
RUANNH 

377444 

$504.55 

—. A 2211-44 


Ready 
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Note that the $$ characters provide for the printing of two additional characters in the number. Since one character 
is a $, the effect is to allow for one additional # designation beyond those typed by the user. 


Exponential format (see above) cannot be used in a field with leading dollar signs. Negative numbers cannot be output 
using the floating dollar character unless the sign is output following the number (see above). 


10.3.3.8 Commas — If one or more commas appear to the left of the decimal point (if any) in a numeric format field, 
then commas are inserted every three digits to the left of the decimal point. A comma to the right of the decimal point 
is considered a printing character. For example: 


LISTNH 

1LO0 FRINT USING ‘#s¢4¢¢¢EE. EE FEE Ee eos TES4S.Se 123.456 
Re acs 

RUNNH 


12°3435.50 123.391 
Reacy 
10.3.3.9 Insufficient Format — If insufficient format characters are present in a field when a number is output, a 


% character is printed in the first position of the field followed by the number in standard format, usually causing 
the field to be widened to the right. The user is guaranteed his entire number. For example: 


LISTNH 

100 FRINT USING ‘’#4.44 £#. #4’ ys 12.3459 ~12.5 
Ready 

RUNNH 


I2<30 42-12-35 
Ready 


Rounding occurs when digits are dropped at the right of numbers. If rounding causes the number to exceed the 
format allowed, the % character is used. For example: 


LOO FRINT USING *.44 okey ~125% 999 
RUNNH 

013 fo 0 P99 

Ready 


10.3.3.10 Format Too Large — If a numeric format field results in an attempt to output more significant digits then 
are available for the number, 0’s are substituted for all digits following the last significant digit. Six significant digits 
are available with the 2-word, single precision math package and 15 digits with the 4-word, double-precision math 
package. Up to 29 formatting characters for single precision and 19 formatting characters for double precision are 


permitted with the PRINT USING statement. An attempt to print fields larger than 29 or 19 results in the following 
error message: 


?PRINT USING BUFFER OVERFLOW 
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In certain cases, a number larger than the format field is truncated without an error message. Good programming practice 
is to check for overflow before attempting to output numbers near the maximum size. 


10.3.3.11 PRINT Statement Punctuation — When the PRINT-USING statement is used, the usual PRINT statement 
punctuation characters (commas and semicolons) have no effect on the output format, except that a comma or semi- 


colon at the end of the PRINT list inhibits termination of the printed line. For example: 


LISTNH 


1OQ FRINT USING * #4 t# ##’ yl eles 


Ready 


RUNNH 
1 a 3 


Re acy 
As another example: 


LISTNH 
1090 
110 


FRINT USING ’#. #7» 


PRIN * x” 
Ready 


RUNNH 
ae OX 


Reacy 
As another example: 


A=1.32519 

\ B=2.45457 

\ LET FS = % A=ee. Ee B=, ee 
OPEN ’LF?’ FOR OUTPUT AS FILE 42 
FRINT #442» USING Fe Ar B 


LOO 
110 
120 
would cause: 
A= 1.33 B= 2,45 
Ready 


to be printed on the line printer. 


10.3.4 MAT PRINT Statement 


The MAT PRINT statement allows for easy printing of a predimensioned matrix. The statement is of the form: 


MAT PRINT {#<expression>,} <matrix name> 
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For example: 


LOG NIM ACL4) 
110 MAT FRINT ACIS) 


If the specified matrix name is unsubscripted, the entire matrix is printed. If the matrix specification is subscripted, the 
subscript(s) indicates the maximum size of the matrix to be printed. 


The matrix name can be followed by a semicolon to indicate that the values are to be printed in a packed fashion, or by 
a comma to indicate that each element is printed in its own zone. For example: 


LISTNH 
100 DIM ACLTGs10) »BC1O0%20) 
116 MAT FRINT As 
IFRINT MATRIX A IN FACKED FORMAT 
Leo MAT FRINT BC1O21Q)s 
PLORX10 MATRIX FPRINTED S VALUES FER LINE 
Re a chy 


Row and column matrices can also be printed. For example: 


LISTNH 
19 OIM ACSI »sBC1O) 
eG MAT FRINT Ags 

1 FRINT MAT A ON ONE LINE 
30 MAT FRINT & 

| PRINT IN COLUMN FORMAT 
Re acy 


Line 30 causes A to be printed as a row matrix, closely packed; line 40 causes B to be printed as a column matrix. 
The form: 


MAT PRINT A, 


would cause the matrix A to be printed as a row matrix, five values per line (at the user terminal). 


10.3.5 PRINT Functions 
In order to aid in formatting simple and complex PRINT statements the following functions are provided: 


POS(X) Retums the current position on the output line; where X is the I/O channel 
number. POS(0%) returns the value for the user’s terminal. 


TAB(X) Tab to position X in the print record. For example, a standard terminal has 
72 printable columns numbered 0 through 71. TAB (4%) causes sufficient 
spaces to be output to move the print head to column 4. If the print head 
is currently past position 4, no spaces are output. 
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For example: 
LOO PRINT *X" -\ NS =< PRBC TOF SFOS(0) 
causes the following to be printed: 


X 10 


9 spaces 


position J Saree | positions 10 and 11 


10.4 INPUT STATEMENT 
The INPUT statement allows data to be entered to a running program from an external device, the user’s keyboard, disk, 
DECtape, paper tape reader, etc. The full form for this statement is: 


INPUT [#<expression>,] <variable list> 
In many cases the simpler form: 
INPUT <variable list> 


is used. This last form causes a ? to be printed at the terminal and the system then waits for the user to respond with the 
appropriate values of string or numeric variables. If a sufficient number of values are not typed, the system prints 
another ?; if too many values are typed, separated by commas, excess values are ignored. The user can also insert 
printed messages between the variables to be input. For example: 


LOO INFUT “YOUR NAME IS’sN%» “ACCOUNT NUMBER’ sA» “THANK YOU’ 
when executed would allow the following interaction at the terminal (the underlined characters are typed by the user): 


RUNNH 

YOUR NAME IS? JOE 
ACCOUNT NUMBER? 347634 
THANK YOU 

Re acy 


ON ERROR GOTO statements can be used in a program to trap recoverable errors which occur during input statement 
execution. The errors shown below occur most frequently when an INPUT statement is executed. 


%DATA FORMAT ERROR Data input in an illegal form 3.4.5 or $2 or #16 or 2;3 or LORA 
(ERR = 50) input for a numeric variable; X’”’ or 
“HELLO” “THERE” input for a 
string variable 


2ILLEGAL NUMBER Overflow or underflow 3E+66 or --23 
(ERR = 52) 


2END OF FILE ON DEVICE Input CTRL/Z 
(ERR = 11) 
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The system assigns values to variables as they are input. Multiple variables can be assigned by separating them in the 
INPUT variable list by commas. Similarly, use commas or the RETURN key to separate values as they are input from 
the keyboard. For example: 


100 INFUT X9¥eZ 
- 10 FRINT XvV¥eZ 
RUNNE 
? 3.414 
P L4992 
3414 14 92 


Re ach 


Do not use commas within a single number; the system ignores all characters input beyond a comma unless another 
variable is to be assigned. For example: 


Right Wrong 
LISTNH LISTNH 
100 INFUT F 100 INFUT FE 

\ PRINT R \ PRINT RK 

Ready Reacts 
RUNNH RLUNNE 
FT 2702 F 257902 
2902 20 
Re a cis Reachy 


Quotation marks (’’) should be used with string variables when embedded commas and spaces are to be preserved. 
For example: 


Right Wrong 
LISTNH LISTNH 
100 INFUT Mt 100 INFUT MS 

\ FRINT ME \ FRINT M# 

Re achy Ready 
RUNNH RUNNH 
? “MOUSE»s MICKEY’ ? MOUSE» MICKEY 
MOUSE» MICKEY MOUSE 
Reascdy Ready 


The format: 


INPUT #<expression>,<string variable> 
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causes input to be read from the file or device indicated in the expression, by the internal file designation number 
given when the file was opened. (See Section 9.2 for a description of the OPEN statement.) If the value of the expres- 
sion is non-zero and the specified file is the user terminal, open as an input device, then no ? character is printed at 
the terminal when input is requested. 


For example: 


_LISTNH 

100 OREN “KB? ’ FOR INFUT AS FILE 2% 
110 INFUT #2298 

120 FRINT & 

Reacts 


The system then pauses while the user types a numeric value for the variable A, although no prompting ? or character 
string message is printed on the terminal. 


RUNNH 

34743 
F478 

Ready 


Another format of the INPUT statement allows the user to enter an entire line of data as a single character string entity, 
regardless of embedded spaces or punctuation. This is different from the normal mode of string input, where the 
comma, apostrophe, single quote and double quote characters have special significance. The format is: 


INPUT LINE {#<expression>,} <string variable> 


For example: 
LO INFUT LINE At 


pauses to allow the user to enter a line followed by the RETURN, FORM FEED, LINE FEED or ESCAPE key (see 
also Section 5.3). Every character input, including quotation marks and commas, is present in A$, above. The end 
of the line being input is the carriage return/line feed sequence (or line feed/carriage return/null or ESCAPE, (see 
Section 5.3) which is appended to the data typed by the user. To remove the end-of-line sequence, use the CVT$$ 
function, described in Section 12.5. 


END OF FILE ON DEVICE (ERR=11) occurs when CTRL/Z is input. 


As another example: 


LOO OREN ‘“F2,.0AT’ FOR INFUT AS FILE 72 
L190 INFUT LINE #749 RE 


These lines cause the system to open a file F2 on the system disk on channel 7 (of 12 possible channels) and to read 
a string of characters up to the next LINE FEED character. 
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10.4.1 MAT INPUT Statement 
The MAT INPUT statement is used to input the values of a pre-dimensioned matrix from a specified input device. Where 
no device is specified, the input is accepted from the user terminal. For example: 


wOO MAT INFUT AC20O) 
causes 20 floating-point values to be accepted as elements of the matrix A. A statement of the form: 
MAT INPUT | #<expression>,}<variable list> 


causes the input to be read from a file or device previously opened on the internal channel indicated by the expression. 


LA QIM BCLO»25) 
2OO OREN “OUTLS0ATAL’ FOR INFUT AS FILE 14 
2 iO MAT INFUT #142 BC1O»25) 


The above lines cause the file DATAI1 on DECtape | to be opened for input on channel | (of 12 possible channels) and 
a matrix of values for the elements of B to be read to fill B(10,25). The zero elements are not assigned a value. When 
input is from channel 0 (i.e., the user terminal), ? is printed; however, reference to another channel does not cause the 
printing of the prompting character. Depending upon the name of the matrix, the MAT INPUT statement allows input 
of floating-point, integer, or character-string values. 


10.4.2 Opening the User Terminal as an I/O Channel 


The internal file designator (following the # character in the INPUT or PRINT statements) is always in the range | to 12. 


File designator 0 is, by definition, always open as the user’s terminal. Internal file designator 0 cannot be closed or 
opened. Use of file #0 is indicated below (no OPEN #0 statement is necessary or allowed). 


LOO INPUT #O9AG 
is equivalent to: 
LOO INFUT At 
It is sometimes useful to be able to request keyboard input without having the ‘“‘?” prompting character printed first. 


This can be accomplished by opening the user’s terminal (“KB:”) on some internal file designator other than 0. The 
? character is only generated for input requests on channel #0, shown in the following example: 


LISTNH 
100 OPEN. ‘KB?’ AS FILE 12 
110 FRINT “WITH USE OF INTERNAL FILE DESIGNATOR’ 
\ PRINT “TYPE YOUR NAME» FOLLOWED BY RETURN KEY’ 
120 INFUT #1%% Ate “THANK YOU’ 
\ PRINT 
\ FRINT 
\ PRINT “FOR COMPARISON» WITHOUT FILE DESTGNATOR’ 
\ PRINT “TYFE YOUR NAME» FOLLOWED BY RETURN KEY’ 
\ INFUT Ass “THANK YOU’ 
32767 ENII 
Ready 
RUNNEH 


WITH USE OF INTERNAL FILE DESTGNATOR 
TYFE YOUR NAME» FOLLOQWED BY RETURN KEY 
Je FP. JONES 

THANK YOU 


FOR COMFARISONys WITHOUT FILE DESIGNATOR 
TYFE YOUR NAME, FOLLOWED BY RETURN KEY 
? de F.. JONES 

THANK YOU 

Reads 
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CHAPTER 11 
VIRTUAL ARRAY STORAGE 


Many applications require a capability to individually address and update records on a disk file in a random (non- 
sequential) manner. Other applications may require more memory for data storage than is economically feasible. BASIC- 
PLUS fills both these requirements with a simple random-access file system called virtual memory. 


The BASIC-PLUS virtual array facility provides a mechanism for the programmer to specify that a particular data 
matrix is not to be stored in the computer memory, but within the RSTS-11 disk file system instead. Data stored in 
disk files external to the user program remain, even after the user leaves his terminal, and can be retrieved by name at a 
later session. Items within the file are individually addressable. In fact, it is the similar treatment of arrays both in 
memory and on random-access files that leads to the term, “virtual array.” 


With the virtual array facility, BASIC-PLUS programs can operate on data structures that are too large to be accommo- 
dated in memory at one time. The disk file system is used for storage of data arrays, and only portions of these files are 
maintained in core at any given time. 


With virtual data storage, the user can reference any element of one or more matrices within the file, no matter where 
in the file that element resides. This random access of data allows the user non-sequential referencing of the data for 
use in any BASIC statement. The virtual memory matrices are read into memory automatically by the system. 


The order in which array elements are referenced can have a significant effect on the program execution time. This 
section therefore describes the algorithms used in the virtual array processor, in order that users concerned with effi- 
ciency can optimize their use of this facility. 


Each disk file appears to the user program as a contiguous sequence of 512-byte records. Any position in a file can be 
specified internally with a 2-component address; the first part being the relative record within the file, and the second 
being the position of the item within the block. One of the functions of the virtual array processor is to transform, or 
map, each virtual array reference into its corresponding file address. 


Virtual arrays are stored as unformatted binary data. This means that no I/O conversions (internal form-to-ASCII) need 
to be performed in storing or retrieving elements in virtual storage. Thus, there is no loss of precision in these arrays 
and no time wasted performing conversions. 


11.1 VIRTUAL MEMORY DIM STATEMENT 
In order for a matrix of data to exist in virtual memory, it must be declared in a special form of the DIM statement. 
This special DIM statement is as follows: 


DIM# <integer constant>,<list> 
where the integer constant is between | and 12 and corresponds to the internal file designator on which the program 
has opened a disk file. The variable list appears as it would in a DIM statement for a matrix in main memory. Thus, a 


100-by-100 matrix could be defined as: 


LOO DIM #12%2 AC1O00%100) 
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Floating-point constants, integer constants and strings can be stored in virtual memory matrices. More than one matrix 
can be specified in one virtual memory file. For example: 


wat NIM #1%9 ACLOOO)s BAC2000)% C#$C2500) 


allocates space for 1000 floating-point numbers, 2000 integer numbers and 2500 character strings (16 characters long). 
However, if a virtual array is defined in this fashion, future references should always dimension the arrays to the same 
size. 


11.2 VIRTUAL ARRAY STRING STORAGE 

One of the few differences in data handling between memory and disk matrices occurs in the storage of strings within 
string matrices in virtual memory. Strings in the computer memory are of variable length from zero characters to any 
arbitrary length. Strings in virtual memory matrices are allocated with a maximum length and may vary from zero 
characters to the specified maximum length (all elements of a single string array have the same maximum length). This 
maximum length can be defined by the program and varies from two characters to 512 characters. The system requires 
the maximum length to be one of the following powers of 2: 


2, 4; 8, 16,32; 64, 128-256, 512 
Each element in the virtual memory string need not use the maximum length available, even though space is reserved 


for each element to be the maximum size. If the user indicates other than one of the values above, he receives the next 
higher size. Thus: 


i 


LOO DIM #1A9 X$¢010) = 6 
is equivalent to: 
100 NIM #ti”s X#C10) = 128 


If no length is specified, a default length of 16 characters is assumed. The maximum length of virtual memory strings 
is specified as an expression in the DIM statement, using the form: 


DIM# <integer constant>,<string>(<dimension>{, <dimension>| ) = <integer constant>} 
For example: 

Lele) VIM #142 A$CLOO0OIF S249 BECLOO=449 C$0100) 
where: 

A$ consists of 101 strings of 32 characters each, maximum. 

B$ consists of 101 strings of 4 characters each, maximum. 


C$ consists of 101 strings of 16 characters each, maximum. 


If a length attribute is given in a DIM statement for a memory string matrix, it is ignored, since memory is allocated 
dynamically to hold a string of any length. 
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11.3 OPENING AND CLOSING A VIRTUAL MEMORY FILE 

In order for the user to reference his virtual core file, he must first associate a disk file (by name) with an internal 
channel designator from 1 to 12 (which is also used in the virtual DIM declaration). This is done with an OPEN, 
OPEN FOR INPUT, or OPEN FOR OUTPUT statement: 


FOR INPUT 
OPEN <string> AS FILE <expression> 
FOR OUTPUT 


where the string is the name of a disk file and the expression specifies an internal file designator (this is the same 
format described in Section 9.2); thus: 


BQ OPEN ‘ACCT’ AS FILE la 


associates the file named ACCT with internal channel 1. If ACCT already exists, then the existing file is used. If 
there is no file named ACCT, one would be created. If the user wishes to destroy an old file named ACCT and create 
a new file of the same name, he can use the statement: 


350 OPEN ‘ACCT’ FOR OUTFUT AS FILE 12 


which causes the file to be deleted if it already exists and a new file created. If the user wants to be alerted that the 
file ACCT is not present, he could write: 


50 OPEN ‘ACCT’ FOR INPUT AS FILE 124 
which would cause an error message to be printed if ACCT is not found. 


NOTE 
Virtual memory arrays do not permit internal 
buffers larger than 512 characters; therefore, the 
RECORDSIZE option is not used when opening a 
virtual core array file. 


11.3.1 Pre-Extending a Virtual Array 

The system overhead for extending a file by a single data element and by many elements is nearly the same. Thus 

it is much more efficient to extend a newly created file immediately to its final length than to extend it many times 
in increments of a single data element. Whenever the eventual size of a file is known, the file should be extended to 
its full size in a single operation. 


For example: 


100 OPEN ‘DATA’ FOR OUTPUT AS FILE ia 
110 DIM#iAs ACLOOOOZ) 
120 ACLQO000Z)=0. 


This extends the virtual array A to its final length. Virtual memory arrays, however, are not initially zeroed by the 
system. In the example given above, A(O) through A(9999) contain indeterminate values. Unless the user is careful 
these values could cause a program failure. The user is advised to first zero the virtual memory array. This could be 
done as follows: 


300 ACIZ%) = 0.0 FOR 1% = O24 TO 100002 
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which both zeros and extends the file to its maximum size. However, this uses the more time-consuming method of 
extending the file. A more optimal approach would be: 


SOO ACI%) = 0.0 FOR I% = 10000% TO 0% STEP -12 


which immediately extends the file to its maximum and then zeros it sequentially. These techniques have frequent 
practical application. 


11.3.2 Closing a Virtual Array File 
The CLOSE statement must be used to terminate I/O between the BASIC program and the virtual array. Once a 
virtual array has been closed, it can be reopened for reading or writing on any internal file designator. 


All virtual arrays must be closed before the end of program execution. The CLOSE statement causes the output of the 
last data element to a virtual memory file. Execution of a CHAIN statement automatically closes any open arrays, but 
does not cause the output of the last data elements to the array. The format of the CLOSE statement is as follows. 


CLOSE <expression>,<expression> ae { 


The expression indicated has the same value as the expression in the OPEN statement and indicates the internal channel 
number of the array to close. Any number of arrays can be closed with a single CLOSE statement; if more than one 
array is to be closed, the expressions are separated by commas. The CLOSE statement writes the current contents of the 
I/O buffer to virtual memory before closing it. This frees memory space for the program to open other arrays or files 

(a maximum of 12 depending upon available space). For example: 


re be CLOSE 2A944 
J4o CLOSE 102 


Line 255 above closes the virtual arrays opened on internal I/O channels 2 and 4. Line 345 closes the array open on 
internal I/O channel 10. 


11.4 VIRTUAL ARRAY PROGRAMMING CONVENTIONS 
Recoverable errors occur when using virtual memory arrays if the user program does any of the following: 


1. References a virtual array without first opening the file. 

2. References a non-disk file (for example, DECtape or the line printer) as a virtual array. 

3. Exceeds virtual memory, that is, defines a matrix that is bigger than the amount of available disk storage 
on the system. 


Remember that a virtual memory file must be closed before stopping the program or chaining to another program. 


11.4.1 Array Storage 

Any data element in a virtual array is completely contained within a single block (512 bytes) of disk storage. This 
restriction has no effect on integers and floating-point items, where the size of data items is fixed, but does limit the 
maximum length of a virtual string to 512 characters. The number of data elements stored in each disk block is a func- 
tion of the size of each element. For virtual strings, the number of elements is also related to the maximum string 
length specified in the DIM# statement. The size of a virtual string defaults to 16 characters and can be specified as: 
2,4, 8, 16, 32, 64, 128, 256, or 512. Table 11-1 indicates the number of array elements stored in each block of a 
virtual file. 


Virtual Array Storage 


Table 11-1 
Virtual Array Storage Capabilities 


Number of Elements 
Data Type per Block 


Integer (%) 


2-Word Floating Point 
4-Word Floating Point 
String ($) 
(where the maximum length = N) 


Strings in virtual memory occupy pre-allocated space in the virtual file, and thus differ from strings in memory, where 
space is allocated dynamically. A disk block containing virtual strings can be considered to be a succession of fields, 
each of the maximum string length. When a virtual string is assigned a new value, it is stored left-justified in the appro- 
priate field. If the new string value is shorter than the maximum length, the remainder of the field is filled with 0’s. 
When the string is retrieved, its length is computed as the maximum string length minus the number of zero-filled bytes. 


11.4.2 Translation of Array Subscripts into File Addresses 

In order to translate an array subscript into a file address, RSTS/E computes (1) the relative distance from the specified 
item to the first item in the array, and then adds (2) the relative distance from the first element of the array to the first 
item in the file. The first quantity (1) is computed from the array subscript and the number of elements per block, as 
shown in Table 11-1. The second number (2) is a constant for each array in a file, and is computed from the parameters 
specified in the DIM# statement. 


Since the DIM# statement contains the only information used to define the structure of a file, it is possible for the user 
to specify different accessing arrangements for the same file in one or more programs. For example, the user can refer- 
ence the same data as either a series of 32-byte strings (A2$) or 16-byte strings (A1$), with the following statements: 


10 QIM #ieAL$¢1000) = 16 116-CHARACTER STRINGS 
2O NIM #1°A28(S500) = 32 1 32-CHARACTER STRINGS 
30 OPEN<‘FILD* AS FICE 12 IVIRTUAL ARRAY FILE 


The user should keep in mind that in BASIC-PLUS array subscripts begin with 0, not 1. An array with dimension n, or 
(n,m) actually contains n+1, or [((n+1)*(mt+1)] elements. 


User programs may define 2-dimensional virtual arrays as well as singly dimensioned ones. Two-dimensional arrays are 
stored on disk (and in memory) linearly, row-by-row. Thus, in the case of an array X(1, 2), the array appears logically as: 


X09 
x10) 


while physically it is stored as: 


lowest address 


highest address 
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If a virtual array is to be referenced sequentially, it is preferable to reference the rows, rather than the columns, in 
sequence. Consider the case in which it is necessary to compute the sum of each row and column in a 2-dimensional 
array. Program 1 does this far more efficiently than program 2. 


Program | 
L.ISTNH 
100 REM — PROGRAM “ONE TO COMPUTE SUMS £FFICTIENELY 
“ARRAY’ CONTAINS VIRTUAL ARRAY 
R(il“2) 15 SUM OF-KOW 7 
L(J42 £8 SUM: OF COLUMN J 
110 DIM #14 9AC1 OAs S04) 
! 10 ROWS» SO COLUMNS 
120 QIM R¢CLOZI» CCSOXL) 
1390 OPEN “ARRKAY’ AS FILE 12 
! OFEN VIRTUAL FILE AND INITIALIZE SUMS WITH MAT 
140 MAT RK = ZER 
\ MAT C = ZER 
130 POR 27. 14 -10-102 
| OPERATE ROW-BY-ROW 
140 FOR J4 = 1A 70 S04 
1! 00 EACH COLUMN IN ROW 
170 RCIA) = RCIA) +t ACTA: JZ) 
| TOTAL ACROSS ROW 
180 Cl JZ). =-EC JA) + ACTA JA? 
! TOTAL TOWN COLUMN 
L9O NEXT J4 
\ NEXT 14 
! COLUMN SUM IS INSIDE LOOF 
2 OO MAT FRINT Ry 


\ MAT FRINT Cs 

! FRINT ROW TOTALS» THEN COLUMN TOTALS 
21Q CLOSE ix 
32/67 ENO 
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Program 2 
LISTNH 
100 REM - FROGRAM ‘TWO’ USES VIRTUAL MEMORY INEFFICIENTLY 
110 QIM #14A9ACLO“4 2304) 
1 10 ROWS» SO COLUMNS 
Lee Pin - KRLLOA) ys CCSO7)D 
ESO OPEN “’ARRAY’ AS FILE 1a 
| OPEN VIRTUAL FILE AND INITIALIZE SUMS WITH MAT 
140 MAT K = ZER 
\ MAT .C = ZER 
130 FOR - JA = 124 70 3024 
| GFRERATE ONE COLUMN AT A TIME 
140 FOR i4- = 12-710 10-n 
| AND ACKOSS ROW 
170 RCTA? = ROAD. t+ ACA JIA) 
f TOTAL ACKOSS ROW 
1SO CCIA? = CCA? FAG Ae? 
1 TOTAL DOWN COLUMN 
190 NEXT Ta 
\N NEAT JA 
ZOO MAT FRINT Re 


\ MAT FRINT C3 

| FRINT ROW TOTALS» THEN COLUMN TOTALS 
21 CLOSE 12 
32767 END 


Re acy 


In virtual arrays two (or more) arrays can share the same file. That is, the following DIM# statement is legal. 
100 DIM #ivy ACLO0O0O)» BACS99)» CC1000) 


The matrix B% begins immediately after the 1000th element of A and the matrix C begins immediately after BZ(999). 
Therefore, the disk layout is as shown in Figure 11-1. 


There is, however, an exception to this rule. Elements in string arrays are allocated a fixed number of bytes in the disk 
file. This is either 2, 4, 8, 16, 32, 64, 128, 256 or 512 bytes of storage. A single string element must not cross a disk 
block boundary (where each disk block contains 512 bytes or 256 words). Consider the following case: 


LOO NIM AAC2)9 BEC 1LOQ0)=4 


The first three words of the disk block are allocated to A%. If the arrays B$ were to begin immediately after A%, one 
of the elements of B$ would cross a block boundary. Hence, B$ begins at the start of the second block in the file 
rather than immediately after A%. 


The rule can be stated as follows: When more than one array is assigned to a single virtual array file, each array begins 
immediately following the last element of the preceding array unless such an allocation would cause an element of the 
array to be split across two disk blocks, in which case the array begins at the start of the next block of the file, and the 
remaining words of the current block are unused. 
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Figure 11-1 Virtual Array File Layout 


11.4.3 Access to Data in Virtual Arrays 

Only a portion of a virtual array is in memory at any given time. This data is transferred directly between the disk and 
an I/O buffer in the user’s area, created when the OPEN statement is executed. This buffer must be 512 bytes (one 
block) long, and may not be specified as several blocks with the RECORDSIZE option in the OPEN statement. For 
each virtual array file, RSTS/E notes (1) the block of the file in the buffer, and (2) whether the data in the buffer has 
been modified since it was read into memory. 


After RSTS/E translates a virtual array address into a file address, it checks whether the block containing the referenced 
item is currently in the buffer. If the necessary block is present the reference proceeds; but if not, another portion of 
the file is read into the buffer. If the current data in the buffer has been altered, it is necessary to rewrite this data on 
the disk prior to reading new data into the buffer. 


The referencing algorithm, which minimizes the number of disk memory accesses generated when handling virtual 
arrays, is flow-charted in Figure 11-2. 


All references to virtual arrays are ultimately located via file addresses relative to the start of the file. No symbolic 
information concerning array names, dimensions, or data types is stored within the file. Thus, different programs may 
use different array names to refer to the data contained within a single virtual array file. The user must be cautious in 
such operations, since it is his responsibility to ensure that all programs referencing a given set of virtual arrays are 
referencing the same data. Consider the following example: 


Le 
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Reference 


Translate Sub- 


script into File 
Address 


Is 
This 
Segment in 


Buffer 
? 


Has 
Current 
Segment Been 


Altered 
? 


Rewrite Segment 
in File 


Clear ‘’Modified”’ 
Indicator 


Read New 
File Segment 


Replacing 
Element in 


Buffer 
? 


No 


Set ‘’Modified’”’ 
Indicator 


Proceed with 
Operation 


Figure 11-2 Virtual Array Addressing Algorithm 
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Program | contains: 


LOO IFROGRAM ONE 
Lio QIM #1» X¢€10)» YC1IO) 
120 GPEN “FILE AS FILE 12 


Program 2 contains: 


100 'FROGRAM TWO 
L10 DIM #1» Z¢€10)» X10) 
120 GREEN “PILE 68 FILE if 


whenever program 2 references the array Z, it is using the data known to program | as array X. Both X and Z are the 
first arrays in their declaration, both contain floating-point data, and both are 11 elements (X(0), . .. , X(10)) long, 
These two arrays, then, correspond in position, type, and dimension. 


References to the array X (in 1) and to the array X (in 2) do not refer to the same data, even though both are using 


the same virtual file (FILE). (The concept of using relative position, rather than name, to identify data items is familiar 


to users of the Fortran COMMON facility.) 


Within a single BASIC-PLUS program it is possible to open a single virtual core array file twice on the same channel for 


the purpose of reallocating the data within the file. For example: 


LOO OPEN ‘TATA’ FOR INFUT AS FILE 124 
110 QIM tly ASC1LOAI=R4Z 
120 NIM tly BSEC4x)=164 


The program now has access to the file DATA through both the array A$ and the array B$. Each element of B$ con- 
tains four elements of A$ (B$(0) is equivalent to the elements A$(0) through A$(3), etc.). Note that the two DIM# 
statements reference that file on a single channel number (#1 in this case). 


Note also that the two statements: 


100 NIM #1» AC1IO“) 
110 DIM #1» BC1O4) 


are not equivalent to the statement: 


109 IM Fly ACLOZI» BCLOZ) 


In the first case the arrays A and B are equivalent to each other and constitute the first array in the file open on 
channel 1. In the second case the arrays A and B are defined as both existing in the file open on channel 1. 
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NOTE 
The user is advised not to open a single file under two 
different channel numbers. For example: 
kee 8 OPEN-“VeLAIES” AS Fite 12 
\ PEN --9alLUES* AS FHLE 22 


2 OO QIM #1lAs X$C202%) 
210 NIM #24 Y$C202%) 


causes two buffers to be created for the storage of 
input to/from channel | and to/from channel 2. If 
changes are made to the same block of the file in both 
buffers, only the changes made in one of the buffers 
is added to the file. The buffer written first is over- 
written by the other buffer; consequently any data 
changed in the first buffer is lost. 


11.4.4 Allocating Disk Storage to Virtual Files 

The dimensions indicated in a DIM# statement set maximum allowable values for subscripts, and are not used to com- 
pute the initial size of the virtual file to be allocated on disk. Instead, the file is created with an initial length of zero 
blocks, and blocks are appended to the file to accommodate the highest referenced file address in the array. This per- 
mits a user to specify array dimensions larger than required at the time the program is written; such programs may 
eventually operate on larger arrays without modification, and without tying up disk storage unnecessarily. 


Areas of unallocated disk storage are found only at the end of a file. 


As blocks are appended to a file, their contents are not initialized to zero. The data previously recorded in a block 
(when it was part of another file) is available to the new owner of the block. Users whose files contain confidential 
information should explicitly overwrite all data in such files, prior to file deletion. In order to protect data contained 
therein. 


To override the dynamic virtual array allocation, the user can reference the last element in the virtual array file. This 
causes all blocks in the file, up to and including the last, to be allocated. As noted above, the contents of these blocks 
as appended to the file are unknown. Using the MAT ZER command is advisable if the program depends on array 
values being initialized to a known (zero) quantity. 


11.4.5 Simultaneous Access of a Virtual Memory Array by Several Programs 

As mentioned in Section 9.2, only the first program to open a file (array) is given write privileges. When a second pro- 
gram attempts to modify an array which is already open, the appropriate block is read from the disk but changed only in 
the second user’s buffer — not on the disk. When the second program references this array and attempts to read another 
block from the disk, a PROTECTION VIOLATION error occurs. This is because the system attempts to update the 

disk with the new information in the current block before the required block is read into memory. Since the second pro- 
gram has no write privileges, the disk cannot be updated. A CLOSE operation at this point also results in a PROTEC- 
TION VIOLATION error for the same reason. Once the job returns to BASIC-PLUS command level and a NEW, OLD 

or RUN command is executed, a CLOSE is performed on all channels. In this case, no write is attempted so the 

CLOSE is successful. 
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The best way to avoid simultaneous write accessing of a virtual core array is to determine whether the user program has 
write privileges. Do this with the STATUS variable (see Section 12.3.5) as shown below. 


£00 OFEN “ARRKAY’ AS FILE 124 

110 IF (STATUS ANTI 102424) 
THEN FRINT “NO WRITE ALLOWED ON ARRAY’ 
4 STOF 

Re achy 


MODE 1% should not be used for updating an array by several programs simultaneously. This is because a user’s buffer 
is modified when an array is opened with the MODE 1% option — the disk is not updated at this time. (Even when the 
first program unlocks the file, allowing other programs to access the array, the first program’s modifications exist only 


in the first user’s buffer.) The array is updated only when the first user accesses data from another block, as explained 
above. 


11.5 PROGRAMMING EXAMPLE 


As an example of virtual core usage, consider the problem of generating a large array of random numbers. Since a 
physical disk block is 256 words, the most efficient array would contain a multiple of 256 elements. The virtual core 
file, ARRAY1.DAT, in this example, contains 5120 data elements in a 2-by-2560 array. The zero row and zero column 
are used, So this array is dimensioned V%(1%,2559%). Twenty physical blocks are used to store this array. The program 


shown below creates the virtual array V% by assigning a random value between 0 and 1000 to each element in the array. 


Lt STNH 

LQOQ OREN “ARRAYI.«UAT’ AS FILE 32 

1O10 NIM #349 VACA 25592) 

LOLO FUR iS = 04 70-24 

1030 VACIAyJ“) = RNDCL) &€ 1000.4 FOR JA = OZ TO 2559% 
LOAD NEXT IA 

LO50 CLOSE 324 


Sef bh? iNT 
he acy 


Now that the file ARRAY1.DAT has been created, the virtual array can be accessed simply by specifying the elements 
by their subscripts. The program shown below prints every 256th value. Notice that the format of the array in the DIM 
statement, below, must be identical to the original format for predictable results. The file’s internal channel number 
and the array’s name can change, but the array must be formatted the same way every time it is accessed. 


L.ISTNH 
L000 OPEN “’ARRAY1.DTIAT’ AS FILE 3% 
1010 DIM #€3%% VAC1%Zs 25592) 


L020 POR  LA4:%).024.70-12% 

1030 FRINT VACIAZA9J5%)5 FOR J%=0Z% TO 2559% STEFF 256% 
1040 NEXT I24 

LOSO CLOSE 32% 

1060 PRINT 

32767 EN 

Ready 

RUNNH 


2Vv4 FOF  FOa BS? 6S. 131 937 7B4 378 796 Shee a ee a 
$25 866 Foe eer 


Ready 
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Values of array elements can be changed simply by redefining them in assignment statements (e.g., LET, INPUT, 
READ). For example, the program below changes the value of specified data elements, once they are defined by 


subscripts. 


LISTNH 


AS FILE 32 


NEW VALUE’ 


L000 OREN “ARRAYI.DAT ’ 
LOLO DIM #3A9 VACLAs 25592) 
1045 ON ERROR GOTO 10580 
LOL0 INFUT “ENTER THE I ANT 
LO30 NA = VACTAs JIA) 
1040 INFUT “ENTER THE 
1043 RINT 
\ FRINT “OLD VALUE WAS: *” 
\ FRINT 
\—8 0 1020 
LOSO Ciwosr Be 
32/67 E NY 
Re acy 
RUNNH 
ENTER THE I ANT 
ENTER THE NEW VALUE? 6006 


OLE VALUE 


ENTER THE 
ENTER THE 


QOL VALUE 


ENTER THE 
ENTER THE 


OLD VALUE 


ENTER: THE. 


Pe @ etch 


WA 


I AND 


6 


578 


NEW VALUE? 333 


WASs 3? 
I AND J LOCATION OF 


NEW VALUE IS¢s 


NEW VALUE IS¢ 


NEW VALUE? 9999 


I ANT 


Ha 


NEW VALUE IS¢ 


yNAY % 


THE ELEMENTT 


J LOCATION OF THE ELEMENT? » 


VACTA: JI“) 


J LOCATION OF THE ELEMENT? O+9 


600 


J LOCATION OF THE ELEMENT? 19255 


333 


7999 


J LOCATION OF THE ELEMENT? 999 


NEW VALUE IS; 


Or 2225 


LAr JIZ% 


“9VACTAy IA) 


Some thought should be given to access methods of virtual arrays. In the above examples, ARRAY1.DAT was allo- 


cated as follows: 


Block 1 
Block 2 
Block 3 


Block 10 


V(0, 0) — V(0, 255) 


B(O, 256) — V(0, 511) 
V(0, 512) — V(0, 767) 


V(0, 2304) — V(0, 2559) 
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Block 11 V(1, 0) — V(1, 255) 


Block 20 V(1, 2304) — V(1, 2559) 


Notice that the second subscript varies from 0 to 2559 for each of the two values (0 and 1) of the first subscript. Since 
the system transfers an entire physical record (that is, a block) from the disk to memory at one time, only one disk 
access is performed for each 256 consecutive data elements (e.g., V(O, 256) — V(O, 511)). It is far more efficient to 
access data elements within a given block than to access data elements in different blocks. 


The two programs shown below access, but do not print, each element in the virtual array. The first access method trans- 


fers anew block to memory for each data element accessed, resulting in 5, 120 disk accesses. The second method, how- 
every, transfers a new block to memory only once per 256 data elements, resulting in only 20 disk accesses. The differ- 
ence in execution time between both methods is quite significant, as shown below. 


Program 1 (Inefficient) 


LISTNH 

1000 OPEN “’ARRAY1.DAT’ AS FILE 32 
LO10 CIM #32» VACA 2559%) 

1015 P=. 7 iMEXV? 

LO20 FOR JZ = OL TO 25592 


1030 A = VACIA»yJ“A) FOR ITA = O4 TO 1A 

1040 NEXT J2 

1045 PRINT “THIS ACCESS TOOK ‘ TIMECO) ~ T “SECONDS. ’ 
1030 CLOSE 32 

32767 END 


Reaay 
RUNNH 
THIS ACCESS TOOK 422 SECONDS. 
Ready 
Program 2 (Efficient) 
LISTNH 
1000 OREN “ARRAYL.DTAT’ AS FILE 32 
1010 RIM #342 VAC14As 25992) 
10135 T = TIMECO) 
1020 POR 72% =. 024 10 i124 
1030 DX = VCCI 9 377 SOR. 4. Oe Tees 
1040 NEXT IA 
19435 FRINT ‘THE SECONDTI ACCESS TOOK’ TIME(O) ~- T ’% SECONDS.’ 
1050 CLOSE 324 
32767 ENII 
Reedy 
RUNNH 


THE SECOND ACCESS TOOK 2 SECONDS. 


Re achy 
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CHAPTER 12 
RECORD I/0 


There are three methods of performing I/O operations in BASIC/PLUS. Formatted ASCII I/O is simple and flexible, 
but requires conversion of numbers by the system from an internal form to an externally usable ASCII representation 
and does not permit random access to files. I/O to virtual memory arrays permits high-speed random access to files 
but can be used only on disk files and does not allow true intermixing of string and numeric elements or use of the 
RECORD-SIZE specification. 


The third type of I/O, Record I/O, permits the user program to have complete control of I/O operations. Properly 
used, Record I/O is the most flexible and efficient technique of data transfer available under BASIC-PLUS. It does, 
however, sacrifice the simplicity of formatted ASCII and virtual array I/O. Less experienced users should first experi- 
ment with the simpler I/O techniques before attempting Record I/O. 


12.1 OPENING A RECORD I/O FILE 
Opening a file for Record I/O requires an OPEN statement, described in Section 9.2. The format of the OPEN statement 
is as follows: 


FOR INPUT 
OPEN<string> AS FILE<expr> 
FOR OUTPUT 


| .RECORDSIZE<expr>} { ,CLUSTERSIZE<expr>} 
| FILESIZE<expr>} { MODE<expr>} 


The RECORDSIZE and CLUSTERSIZE options can be specified for Record I/O files as described in Sections 9.2.1 
and 9.2.2. 


The use of all optional clauses depends on the particular device being accessed. The optional clauses are described 
extensively in the RSTS/E Programming Manual. 


12.2 CLOSING A RECORD I/O FILE 
Each Record I/O file must be closed once I/O operations on that file are completed. Files are closed with the CLOSE 
statement, as described in Section 9.3. The CLOSE statement is of the form: 


CLOSE<expr>{,<expr>} 
where the value of each expression specifies one of the 12 I/O channels. 
Remember, the CLOSE statement for formatted ASCII and virtual array files causes the final record of the file to be 
written before closing the file. However, all I/O operations to Record I/O files are explicitly performed (with GET and 


PUT statements). For this reason, be sure the user program explicitly writes the last record onto a Record I/O file 
before executing a CLOSE. 


tged 
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12.3 THE GET AND PUT STATEMENTS 

Input and output operations to Record I/O files are performed directly between the device channel and the I/O buffer 
created by the OPEN statement. All I/O is specified in terms of single records, using the GET and PUT statements. 
GET and PUT are of the form: : 


GET#<expr1> {,RECORD<expr2>} 
PUT #<expr1> |, RECORD<expr2>} {,COUNT<expr3>} 


If the RECORD option (see Section 12.3.3) is not used, the GET statement reads the next sequential record from the 
file open on the channel designated by <exprl>. The record is placed in the I/O buffer that was associated with the 

channel by the OPEN statement. The size of the record depends upon the characteristics of the device on which the 

file resides, as described in Table 12-1. In Record I/O, the RECORD option refers to a sector whose length is device- 
specific, not to a logical data record. 


When the RECORD option is used in a GET or PUT statement, a specific record, or sector, is accessed. For example: 
10 GET #424: RECORD SA 


reads the eighth sector of the file opened on channel 4 into the user I/O buffer. Notice that the preceding seven sectors 
of the file need not be read. 


Table 12-1 
Device Record Characteristics 


Input Record Characteristics 


Records (sometimes called blocks or segments) are normally 512 bytes long. 
When the RECORDSIZE option is specified in the OPEN statement, and a 
buffer longer than 512 bytes is created, the system reads as many full 
records as possible. If several disk blocks are read with a single GET state- 
ment, the next sequential record is that record immediately following the 
last block read. 


RECORDSIZE must be an even number. If RECORDSIZE is not a multiple 
of 512 bytes, the last block in the transfer is only partially transferred. The 
remainder of the block is discarded. In non-file-structured operation, the 
default record size is dependent on the device cluster size. 


DECtape For file-structured DECtape, records are always 510 bytes long. For non-file- 
structured DECtape, records are always 512 characters. 


magtape When performing file-structured I/O, magtape records are normally 512 char- 
acters. With non-file-structured I/O, magtape records can be of any length; only 
one record can be read per GET statement; and the record length can not exceed 
the buffer size as determined by the RECORDSIZE option. 


keyboard The GET #0 statement (or a GET on any channel associated with the keyboard) 
obtains one line from the keyboard, up to the first line delimiter (CTRL/Z, 
RETURN, LINE FEED, ESCAPE, FORM FEED or CTRL/D). 


card reader A record consists of a single card. The RECORDSIZE option has no effect on 
card reader input. 


paper tape RSTS/E reads a full buffer of input from the paper tape reader unless an 
end-of-tape is detected. 
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Similarly, if the COUNT and RECORD (see Sections 12.3.2 and 12.3.3) options are not used, the PUT statement 
writes the contents of the I/O buffer for the specified I/O channel onto the next sequential record of the file. The 
expression <exprl> specifies the internal channel number on which the file was opened. The PUT statement writes 

a single record on the device, with the exception of disk files which permit several records to be written with one PUT 
statement (when the RECORDSIZE option in the OPEN statement is used to increase I/O buffer size). 


To avoid having to move the contents of an input buffer to an output buffer (as when copying from one file to 
another, for example) the alternate buffer I/O technique is recommended. In this technique, <expr1> of the GET and 
PUT statements is as follows: 


SWAP%(B%) + 1% 


where B% is the channel number of the buffer to be used, and I% is the channel number on which the I/O activity 
occurs. 


The following example shows a fast copy, using the alternate buffer technique. 


100 ON ERROR GOTO 9000 
110 INFUT “ENTER INFUT CHANNEL NUMBER’s IZ 
\ INFUT “ENTER OUTFUT CHANNEL NUMBER’» O% 
120 OPEN “INFUT’ FOR INFUT AS FILE Iz 
130 OFEN ‘OUTPUT’ FOR OQUTFUT AS FILE O2% 
140 GET #124 
\ PUT #SWAPZCI“Z) + O24 
\ GOTO 140 
160 CLOSE #124» #07 


N PRING "Ff iLe COPIED 
\ GOTO 32767 
7000 IF ERR=114 AND ERL=302 
THEN RESUME 160 
ELSE ON ERROR GOTO 0 
! ACCEPT END-OF-FILE ON INFUT 
32767 END 


12.3.1 The RECOUNT Variable 

Non-file-structured devices, as can be seen in the description of the GET statement, can read less than a full buffer of 
data. To permit the program to determine how much data was actually read, a system variable, RECOUNT, con- 
tains the number of characters read following every input operation. RECOUNT is used primarily for non-file- 
structured input; however, it may also be used with file-structured devices. 


RECOUNT is set by every input operation on any channel (including channel 0). It is, therefore, essential that the 
RECOUNT value be tested or copied immediately following the GET statement. RECOUNT is not properly set if 
any error Occurs in the operation. 


12.3.2 The COUNT Option 
The COUNT option used in a PUT statement with a non-file-structured device specifies the number of characters to 
write in the current record. However, the COUNT expression cannot be greater than the size of the I/O buffer. 


For example, where internal channel | is opened as magtape unit O (non-file-structured magtape), the following 
statement could be used to write an 80-character record: 


LOO PUT #149 COUNT 804 
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When COUNT is not used, the PUT statement writes an entire buffer, regardless of whether the buffer contains 
data. 


COUNT must be used when writing a disk file that was opened with RECORDSIZE not a multiple of 512. 


12.3.3 The RECORD Option 

With disk files, the user has the capability of performing random access I/O to any record of the file. Records in a 
disk file are always 512 characters long and are logically numbered within the file from 1 to n, where n is the size of 
the file. 


The RECORD expression provides the logical record number of the file to the GET or PUT statement. For example, 
assuming a disk file opened on internal channel 1, the following statement writes the contents of the I/O buffer 
associated with channel | on records 10 through 99 of that disk file: 


ZOO PUT #1%2 RECORD I% FOR I4A=10% TO 992A 
More than one physical record or block can be read or written by assigning a large I/O buffer to the file with the 


RECORDSIZE option in the OPEN statement. (The size of the buffer does not affect the numbering of the records 
within the file.) 


If the disk file on channel 1 were opened with a RECORDSIZE of 1024 characters (which would cause two 512- 
character records to be written with each PUT) the PUT statement would be written as follows: 


2OO PUT #1242 RECORD I% FOR I% = 10% 70 282 _SteEP 22 


After performing a random access GET or PUT on a disk file, the next GET or PUT statement on that channel accesses 
the next sequential record if no RECORD number is specified. For example: 


2Pd OPEN ‘DATA’ AS FILE 1%+ RECORDSIZE Si2% 
300 GET #14 RECORD 99% 
310 FUT #124 


The PUT statement at line 310 writes record 100 of the disk file. 


12.3.4 BUFSIZ Function 

In certain applications, it is important for a program to determine the buffer size of an open channel, especially if the- 
OPEN statement specifies a logical device name. The user program can execute the integer function BUFSIZ to 
extract this information. 


The BUFSIZ function returns an integer value telling the size of the buffer for a specified open channel. For example: 
Y% = BUFSIZ(NZ%) 


The statement returns to Y% the size of the buffer in number of bytes for channel N%. If the channel is closed, the 
function returns 0 to Y%. 


12.3.5 STATUS Variable 

The variable STATUS contains information concerning the last channel on which a user program executed an OPEN 
statement. The variable is a 16-bit word, each bit of which the user program can test to determine status. Table 12-2 
shows the information, the tests, and the meaning of each bit. 
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Table 12-2 
RSTS Variable STATUS 


The first eight bits of the word contain the handler index. 
The following values apply for various devices. 


Disk 12 Card Reader 
Keyboard 14 Magtape 


DECtape 16 PK: device 
(pseudo-keyboard) 


Line Printer DX: device 
(floppy disk) 
Paper Tape Reader RJ: device 
(2780 remote job entry) 


Paper Tape Punch Null device NL: 
DMC 11 


(STATUS AND 256%)<>0% The device is open in non-file structured mode or is character- 
istically non-file structured. 


(STATUS AND 512%)<>0% The job does not have read access to the device. 
(STATUS AND 1024%)<>0% The job does not have write access to the device. 


(STATUS AND 2048%)<>0% The device maintains its own horizontal position. Such 
devices are keyboard and line printer type. 


(STATUS AND 4096%)<>0% The device accepts modifiers. Such devices use the record 
number as a modifier word rather than a physical position of 
the device. Keyboard, line printer, and card reader are 
such devices. 


(STATUS AND 8192%)<>0% Device is a character device. 
(STATUS AND 16384%)<>0% Device is an interactive type (keyboard). 


(STATUS <0%) Device is a random access blocked device, such as disk and 
non-file-structured DECtape. 


12.4 WORKING WITH RECORD I/O FILES 

Techniques for opening, closing, reading and writing Record I/O files have been described. But these techniques apply 
only to indivisible I/O buffers associated with internal channels; no mention has been made of manipulating data within 
these buffers. Techniques for moving data into or out of a buffer are provided by extensions to the BASIC language. 
The FIELD, LSET and RSET statements permit the program to access and modify the contents of an I/O buffer, 
character by character. These statements are discussed in the following sections. 


12.4.1 Extending Disk Files 


A disk file that is created by an OPEN FOR OUTPUT (or OPEN) statement has a length of 0. As records are written, 
the file progressively grows in length; this growth is called extending the file. 
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A more exact description of file extending is as follows: 


1. Is there room in the last cluster’ of the file for the new record? 

2. If so, then the file length is increased and previously unused space in that cluster is used. 

3. If not, then a new cluster is appended to the file. There is then room in the newest last cluster for the 
new record so condition 2 applies. 


The amount of space actually allocated by the system to a file may be greater than the file length. For example, if the 
file clustersize is 4 and the first 6 records of that file have been written, the file is of length 6 but is actually allocated 
8 blocks (2 clusters) of space. 


A file is extended by attempting to write beyond the current end-of-file. Hence, a program must have write privileges 

in order to be able to extend a file. There is an exception to the rule that having write access to a file permits a 

program to extend the file. When a file is opened for update (see Section 12.4.5) several programs can have simultaneous 
write privileges on a single file. Nonetheless, if a program opens a file in update mode, that file can not be extended. 

A file can be extended only when open in normal (non-update) mode. 


It is possible to extend a file by a number of records at one time. For example: 


100 OPEN “QATA’ FOR QUTFUT AS FILE 1x 
L110 PUT #la»s RECORD 100% 


creates a file DATA and (when line 200 is executed) extends it immediately to 100 records. Since the system over- 
head for extending a file by a single record and by many records is nearly the same, it is much more efficient to 
immediately extend a newly created file to its final length than to extend it many times in increments of a single 
record. Whenever the final size of a file is known, the file should be extended to its full size in a single operation. 


12.4.2 The FIELD Statement 
The FIELD statement is used to dynamically associate string names with all or part of an I/O buffer. The FIELD 
statement has the form: 


FIELD #<expr>, <expr1> AS <stringvar1> 
[,<expr2> AS <stringvar2>.. .] 
where <expr> is an internal channel number associated with some file by an OPEN statement; <expr1> is the length, 
in characters, of the associated string variable; and <stringvar1> is a unique string variable name. The names are 


associated from left to right with successive characters in the I/O buffer assigned to the designated internal channel 
number. For example: 


73 FIELD #24» 10% AS Atty 20% AS Bte 34% AS FH 


cee a ame 
10 =| «—— 20 ——»| 3 In 


5 12-byte buffer AAA 


1The CLUSTERSIZE defines the minimum increment by which a file can be extended on the disk. A file need not occupy all blocks 
within the cluster. 
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As shown in the previous diagram, statement 75 associates three strings, A$, B$, and F$ in the I/O buffer, with lengths 
of 10, 20, and 3 characters, respectively. The total number of characters represented in this statement is 33. The total 
number of characters must be less than or equal to the actual I/O buffer size (which is dependent on the device and 
the RECORDSIZE option, as described in Section 9.2.1). 


FIELD statements do not move data but rather permit direct access to sections of the I/O buffer via string variables. 
The effect upon a string variable is temporary and is nullified by any attempt to assign a value to the variable (other 
than the LSET and RSET, described in Section 12.4.3). For example: 


LOO UPEN F731 EAS Fie ee 
110 FIELO 3NGN#249 SA AS At 
L2o LET A$ = “ARCYE® 


Line 120 causes the string variable A$ to be removed from the I/O buffer. The string ABCDE is not stored in the I/O 
buffer by line 120. 


A FIELD statement is an executable statement, rather than a compiler directive (such as a DIM statement). To illus- 
trate: suppose that each block of a disk file contains sixteen 32-character subrecords and that each record consists of 
one 5-character field and one 27-character field. In order to extract the eighth subrecord from the I/O buffer, the 
following statement could be executed: 


2 OO FIELD #149 22424 AS [ty SA AS By 27% AS AF 


bytes BS 


Line 200 causes the string variables B$ and A$ to point to the desired subrecord. The string D$ is created to permit 
the first seven subrecords (7*32=224) to be skipped. An even more general statement could be used to obtain any of 
the subrecords in the I/O buffer, as follows: 


190 FOR ITA = O04 TO 154% 
2 OO FELD #lA»y (LA-14)x324 AS [$s SA AS Bey 272% AS AS 
2 iO NEXT Ia 


BS BS BS BS BS 


BS BS BS BS 
[las [Jas [las [las [las [las | las |Jas || as 


1%=1 I%~=2  I%=3 1I%=4 I1%=5 I%=6 I1%=7 I%=8 1%=9 


o{ 06 je} 2} ft 


When the statement above is executed, I% should contain the number of the subrecord that B$ and A$ are to contain, 
as an integer from | to 16. When I%=1, for example, the expression (1%- 1%)*32% equals 0, so B$ points to the first 
subrecord in the buffer. When I%=2, however, the expression (I1%- 1%)*32% equals 32, so B$ now points to the first 
subrecord beyond the 32nd character of the buffer. Each single increment of 1% moves B$ 32 characters further into 
the buffer. 
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Subscripted string variables can also be used in FIELD statements. For example, the following statements could be 
used to allocate the subrecords, described in the previous example, to two string arrays: 


300 DIM ASCITSAZ)» BEC1S4) 

310 FOR Iz = OA TO 154 

320 FIELD #14 TAKS2% AS [$s SA AS BCT AZ» 27K AS ASCIZ) 
330 NEXT IZ 


BS$(0) BS(1) BS(2) BS$(3) BS(4) BS(5) BS(6) BS$(7) 


[oe Toe os Tw To [Lo 


I D$ 


With each iteration of the FIELD statement at line 320 the dummy string D$ increases by 32 characters, making the 
displacement from the start of the I/O buffer to the string B$(I%) equal to 32 times 1% characters. Once this loop is 
executed, the position of each string in the arrays A$ and BS is fixed, A$(0) and B$(0) pointing to the first subrecord 
and A$(15) and B$(15) to the last. 


However, virtual array strings must not be defined as string variables in a FIELD statement. When strings are defined 
as virtual arrays they are required to be in a fixed place in both a disk file and the I/O buffer for that file. Attempting 
to specify a virtual array string variable in a FIELD statement has no effect on the virtual array string. 


12.4.3 LSET and RSET Statements 

Once the strings have been defined as part of the I/O buffer by a FIELD statement, values in these strings can be 
stored without moving them from the I/O buffer. The LSET and RSET statements store values in a string without 
redefining the string position. These statements are of the form: 


LSET <stringvar> | <stringvar> = | = <string> 
RSET <stringvar> | <stringvar>.. = = <string> 


where <stringvar> represents any legal existing string variable name (multiple string variable names can be separated 
by commas) and <string> represents any legal string expression. 


The LSET and RSET statements store the value of the string expression into the designated string or strings. The 
string previously stored in the variable is overwritten. The length of the string is not changed; if the new string is 
longer than the existing string, the new value is truncated. If the new string is shorter than the existing string, it is 
either padded with spaces on the right by LSET or padded with spaces on the left with RSET. LSET, then, causes 
the string to be left-justified in the field and RSET causes the string to be right-justified. 


The normal use of LSET and RSET, as described in this section, is to store data in strings allocated within an I/O 
buffer by a FIELD statement. LSET and RSET can be used to assign a value to any string variable within a BASIC- 
PLUS program. 


12.4.4 Differences Between the LET Statement and the LSET/RSET Statement 
The LET statement cannot be used to place string values into an I/O buffer because it causes the string to be redefined 
elsewhere. Another restriction on LET occurs when that statement is used to equate two strings, as follows: 


100 LET A$ = BS 
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To avoid unnecessary character manipulation, this operation causes A$ and B$ to reference the same string in memory. 
Normally, any operation which alters B$ causes that string to be moved, so no conflict arises. However, LSET and RSET 
do not move strings; they alter existing strings in a fixed position. 


Therefore, if the value of B$ in line 50 above were altered by an LSET or RSET statement, the value of A$ also 
changes. For example: 


400 BS = ‘ARC’ 
410 A$ = Re 
420 LSET §¢ = XYZ" 


Both A$ and B$ contain “XYZ” following the execution of line 420. 


This phenomenon has another ramification; if the string B$ in this example had been defined by a field statement as 
being in some I/O buffer, the string A$ would also be in the I/O buffer (being identical to B$). Executing a GET 
statement to read another record into the I/O buffer would then change the value of A$ as well as BS. For this reason, 
LSET and RSET should be used only for Record I/O operations; using these statements for other purposes may cause 
peculiar results. 


When the strings A$ and B$ should not be physically identical, the string B$ can be moved into the string A$ as follows: 
300 LET AS = Bh + 77 


Line number 300 appends a null string to B$, which has no effect on the string A$ but causes the two strings to occupy 
different storage areas. 


12.5 CVT CONVERSION FUNCTIONS 

The FIELD, LSET, and RSET statements allow a program to store or retrieve string data directly from an I/O buffer. 
To permit floating-point and integer values in Record I/O files, four conversion functions are provided as described 
in Table 12-3. A fifth conversion function facilitates character string manipulation. 


Four of the functions do not affect the value of the data, but rather its storage format. Each character in a string 
requires one byte of storage (8 bits); hence, characters may assume (decimal) values from 0 through 255 and no others. 
A 16-bit quantity can be defined as either an integer or a 2-character string; 2-word floating-point numbers can equally 
be defined as 4-character strings. 


The CVT functions that change storage format perform two important functions: first, they permit dense packing of 
data in records. For example, any integer value between - 32768 and 32767 can be packed in a record in two characters 
using CVT%$; this would only be true for integers between -9 and 99 if the data were stored as ASCII characters. 
Second, converting the internal numeric representation to an ASCII string (as with the NUM$ function) is a more time- 
consuming process than that performed by the CVT functions. Thus, the CVT functions speed the processing of a 

large amount of data within a file. 


The CVT$$ function manipulates a character string and generates a new character string. This action is unlike other 
CVT functions because it does not change the internal format of the data, but rather alters the contents of the string. 
The output string is converted according to an integer value given by the user program and can be any value or sum of 
any values listed in Table 12-3. 


The value 1% in the CVT$$ function removes the parity bit (most significant bit) from each character in the string. 
Under RSTS/E, characters are usually represented with no parity. All comparison of characters assume no parity. 

The value 2% removes all space characters (CHR$(32)) and horizontal tab characters (CHR$(91)) from the string 
while values 8%, 16%, and 128% remove only selective occurrences of space and horizontal tab characters. The termi- 
nating and excess characters removed by the value 4% in the CVT$$ function usually have no informational value in a 
string. 
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Table 12-3 
CVT Conversion Functions 


A$ = CVT%S$ (1%) 
1% = CVT$% (A$) 


Maps an integer into a 2-character string. 


Maps the first two characters of a string into an integer. If the 
string has fewer than two characters, null characters are 
appended as required. 


A$ = CVTFS (X) Maps a floating-point number into a 4- or 8-character string 
(depending upon whether the 2-word or 4-word math pack- 
age, respectively, is being used on the system). The current 


math package can be determined by examining LEN(CVTF$ 
(0)). 


Maps the first four or eight characters (depending upon 
whether the 2-word or 4-word math package, respectively, is 
being used on the system) of a string into a floating-point 
number. If the string has fewer than the required number of 
characters, null characters are appended. 


X = CVTSF (AS) 


T$ =CVTS$$ (S$,M%) Converts the source character string S$ to the string referenced 


by the variable T$. The conversion is performed according to 
the decimal value of the integer represented by M% as follows: 


1% Trim the parity bit. 


2% Discard all spaces and tabs. 
4% Discard excess characters: CR, LF, FF, ESC, 
RUBOUT, and NULL. 


8% Discard leading spaces and tabs. 
16% Reduce spaces and tabs to one space. 
32% Convert lower case to upper case. 
64% Convert [ to ( and | to ). 
128% Discard trailing spaces and tabs. 
256% Do not alter characters inside quotes. 


The value 32% converts all lower-case characters in a string to upper-case. This feature is valuable since some terminals 
transmit both forms of alphabetic characters. The lower-case characters are between CHR$(97) and CHR$(122) and 
upper-case characters are between CHR$(65) and CHR$(90). 


The value 64% in the CVT$$ function enables BASIC-PLUS programs to accept the parenthesis and square bracket — 
characters ad delimiters of a project-programmer number. This action is desirable when handling account numbers 
from terminals not having the square bracket characters since most terminal devices have the parenthesis characters. 


The value 256% in the CVT$$ function forbids any alteration of characters inside quotes, except parity bit trimming -- 


set by M%=1%. Regardless of other values in the parameter M%, when 256% is included no operations are performed 
in the source string on characters within quotes. 
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Generally, the precedence of operations performed on the string is in increasing order of the individual values in the 
parameter M%. (The 256% value, however, is the exception; its precedence ranks between 1% and 2%.) This order 
implicitly determines which subsequent operations are performed on the string. For example, if the characters in the 
source string have their parity bit set and the parity trimming option is not selected, subsequent comparisons 
required by other options might not be successful because comparisons are made against ASCII characters with no 
parity. For example, a space (SP) character, which is CHR$(32) in no parity or odd parity form, does not compare 
with a space (SP) character which is CHR$ (160), its even parity form. 


Keeping the parity bit in the input character of the string is important in text processing applications where the parity 
bit of each character is possibly a flag rather than a parity bit. As a result, such flagged characters are not changed or 
discarded if the parity trimming option is not selected. 


The precedence of operations affects the result of values given in the CVT$$ function. If the values 2%, 8%, 16%, and 
128% (154% or greater) are given in the CVT$$ function, the values 8%, 16%, and 128% have no effect on the output 
string since the first option performed (2%) removes all space and tab characters from the string and the remaining 
values dealing with space and tab characters have no effect. In like manner, the value 16% applies to all space and tab 
characters not discarded by the 2% and 8% options. Accordingly, to maintain at least a single space interval in a 
string, the user program must give the 16% value and omit the 2% and 8% values. 


The use of the CVT$$ function in general eliminates the need for special code in BASIC-PLUS programs handling 
string input. For example, the following code at lines numbered 110 through 150 manipulates an input string. 


LISTNH 

wh QIM ASACLI282) 

SO Ni“z = 14 

LOO PRIN: “fYFE- THE INPUT STRING’ 3 
\ INFUT LINE ASS 

LL Té = FNCE&$CAG6S) 

120 NEF FNC&E CASS) 

1.30 CHANGE A&$ TO AGZ 
\ 164 = O2% 

140 FOR X64 = NIA TO AGZCOZ) 
N IF AGACXG6AZ) <= 32% OF AGACXGA) & GSA 


THEN GOTO 150 
ELSE J64. = J64 ¥ NZ 
\N AGACIGAD = AGACX6Z) 
150 NEXT X&2% 
N AGACOAD = 64 
\ CHANGE ASA TO ASS 
\ FNCS$ = ASS 
\ FNENTD 
149 PRIN 1%. =. "2.1% 
\ 5D -fO-300 
32767 ENT 


Rie secdty 
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RUNNH 

TYPE THE INFUT STRING? EVs PICEA. tava ) 30 I 

Té$ = NEV3FILE-EXTL100%1007 

TYPE THE INPUT SERING?T “THE LIFE OFANAN @ PEBBLE IS. GQUICKS 

LIKE UNTO THE ESSENCE OF A GREEN ARROW, ’ 

Th = “THELTIFEOFAPEBRBLETSQUICK PL IKEUNTOTHEESSENCE OF AGREENARROW. ” 
TIPE THE INPUT. STRING? Co 


Re acy 


Lines 110 through 150 can be replaced by a single CVT$$ function statement at line 110 as shown in the sample code 
below. 


LISTNH 

100 PRINT “TYPE THE INPUT SIRING’? 
\ INFUT LINE A&éS 

110 Th = CUTE$ (A6$e 72) 

140 PRING "tS =") 1s 


Veg EG 100 
32767 ENT 


React 
The value 7% in the CVT$$ function is the sum of 1%, 2%, and 4%. The CVT$$ function with a value 7% causes the 


same results as the code of the user-defined function FNC6$. The following sample dialog shows the effect of the value 
7% at line 110. 


TYFE THE INFUT STRING? DEV’ FILE ster. 1300e4 0-0 3 
TS = TEViFILE-«EXTC100%100I 
TYPE THE INPUT - STRING? -“C 


The value 255% in the CVT$$ function at line 110 produces the results shown by the following sample dialog. 
TYPE THE INFUT STRING? DEV PIL ake LCG 100] 
Té = DEVtSFILE.«-EXT¢100%100) 
EYPE. tHe. -INEUT STRING? Cc 


The following sample dialog shows the effect of the value 189% (1%+4%+8%t 16%+32%+ 128%). 


KUNNH 
EYPE THE INPUT STRING? HE SALE *1- AM SURE 
te es ST KNOW. * 


T&# = HE SAITty "I AM SURE I « « + DON’T KNOW." 
TYPE THE INPUT STRING? “C 


12.6 EXAMPLES OF RECORD I/O USAGE 


In Figure 12-1, the device KB: is opened with the default size (128 characters) buffer length by the OPEN statement 
at line 10. 
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LISTNH 
10 OPEN "KES" FOR OUTPUT AS FILE 12 
2Q FIELD #142 10% AS Aty 104 AS EBty 10% AS CH 
30 LSET AS = 41235457 
\- RSET BS = “467870° 
\ RSET CS = “VWKYZ’ 
40 FUT #14» COUNT 3024 


32767 ENT 
Ready 
Figure 12-1 Record I/O Example #1 


The FIELD statement at line 20 defines three 10-character segments of the buffer as A$, B$, and C$. LSET at line 30 
positions “12345” in the leftmost 5 of the first 10 characters of the buffer via the pointer A$. Similarly the second 
and third 10-character pieces of the buffer are set by RSET statements. When run, this program generates: 


RUNNH 
12345 567890 VWXYZ 
Ready 


Note that no carriage return/line feed was output by the PUT statement. (The Monitor outputs a CR/LF sequence as 
the first part of the READY message.) 


Figure 12-2 is a program to move data from a file named “SNOOPY.BAS” in the system library (note the $ in the 
filename) onto the line printer. Both the line printer and the disk file buffers are initialized to 512 characters. The 
FIELD statements at lines 140 and 150 set A$ and B$ to refer to these buffers. Data read at line 160 is transferred to 
the line printer buffer by the LSET statement (RSET would also be acceptable in this one case, since both A$ and B$ 
are the same length) at line 170. Then, at line 180, this data is output to the line printer. The loop terminates on end-of- 
file on attempting to read past the last block of the SNOOPY.BAS file via the ON ERROR GOTO mechanism. Note 
that the example at the end of Section 12.3 shows a more efficient technique to do this. 


LISTNH 

119 OFEN “$SNOOFY.BAS’ AS FILE 1% 
120 ON ERROR GOTO 200 

130 OPEN ‘LPs’ FOR OUTPUT AS FILE 2%* RECORDSIZE 512% 
140 FIELD #14» Si22z AS AS 

150 FIELD #24» S124 AS Bt 

140 GET #12 

170 LSET B& = AG 

180 FUT #22 

190 GOTO 160 

200 CLOSE Ay 22 


oa/ Os ENII 
Ready 
Figure 12-2 Record I/O Example #2 


FIELD statements can be used to perform blocking and deblocking of records where appropriate, as in Figure 12-3. 
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100 GET #22 

L190 FOR X42=0Z%4 TO 420% STEF 80% 
120 FIELD #24» XA AS Aty 80% AS Bt 
1L8O NEXT X% 

190 PUT #22 


Figure 12-3 FIELD Statement Example 


Figure 12-4 illustrates the use of the CVT functions to store numerical data in compact form as strings of binary types. 
The tape punched by this program has each integer represented on two frames of tape. A similar program could be 
written to read this binary tape. 


LISTNH 

100 DIM A$C99Z) 

110 OPEN “FFs FOR OUTFUT AS FILE 1%» RECORDISIZE 200% 
L2Q FIELO #iazy 2.xIT AS 2%» 2. AS ACT) FOR I = O. TM 99, 
130 LSET ASC TA) = CVTA$C(IZ) FOR I4=0% TO 99% 

140 PUY #124 

150 CLOSE 12 


32767 ENT 
Ready 
Figure 12-4 CVT Function Example 


12.7 THE XLATE FUNCTION 

The XLATE function is provided to translate a string from one storage code into another. For example, while reading 
a magtape file, it might be necessary to translate from EBCDIC code to ASCII code so that data could be processed 
by the PDP-11. The XLATE function is of the form: 


XLATE (<string1>,<string2>) 
For example: 
X$ = XLATE(A$,B$) 


The first argument, <stringl>, is the source string, the second argument <string2>, is the table string; the string value 
returned by XLATE is called the target string. Characters are taken sequentially from the source string, and the value 
of each character (0 to 255) is used as an index into the table string (that is, 0 means the first character of the table 
string, 1 means the second, etc.). The character value from the table string is appended to the target string unless the 
selected character in the table string has a value of 0 or the table string is shorter than the index value. This means that 
the target string is equal to or shorter than the source string. 


For example, the following program removes all characters except “‘0”’ to “9” and changes the characters “‘8”’ and 
i? ae into ee Pe and nice as 
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LISTNH 
LOO TE = “QO1L234567AB" 
L116 TS = CHR¢(0O4) + T$ FOR IA = OX% TO 472 
| LINE 110 FUT 0O’°S CORRESFONDTDING TO CONES 0 TO 47 
120 INFUT S# ! GET STRING TO TRANSLATE 
130 PRINT XLATECS#s T#) 
32767 ENT! 
Re schy 
RUNNH 
P 1234567890 DIGITS --- ABCKDEFGHIJKLMNOF QRS TUVWXYZ 
L2S4567AK0 
Reach 
RUNNE 


PO LAXXXS4ABCUEOS7 JIKRKLMNSS 7891 230EFGHILSS7986 
L2s4OR/S546/7ABRL 231357 R06 


Re ech 
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APPENDICES 


The following pages contain a summary of the BASIC-PLUS language, the commands described in the RSTS/E System 
User’s Guide, and error messages. 
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BASIC-PLUS 


A.1 SUMMARY OF VARIABLE TYPES 


Type 


Floating Point 


Integer 
Character String 


Floating Point 
Matrix 


Integer Matrix 


Character String 
Matrix 


Variable Name 


Single letter optionally followed by A 
a single digit I 

X3 
Any floating point variable name B% 
followed by a % character D7% 
Any floating point variable name M$ 
followed by a $ character RI$ 
Any floating point variable name S(4) 
followed by one or two dimension N2(8) 
elements in parentheses 
Any integer variable name followed A%(2) 
by one or two dimension elements E3%(4) 
in parentheses 
Any character string variable name C$(1) 
followed by one or two dimension A2$(8) 


elements in parentheses 


NOTE 
When operating in EXTEND mode, the variable name 
may consist of a letter, followed by 0 to 29 additional 
characters, each a letter, digit or a dot (i.e., a period, 
or point). The rules for specifying integers, strings, and 
dimension elements remain the same for EXTEND 


mode. 


Examples 
PER.DIEM.FACTOR 
L% 


BRANCH.CONTROL% 
HEADING.A31.FORM$ 
DECK.OF.CARDSS(3,12) 


A-1 


(floating point variable) 


(integer valid also in NO 
EXTEND) 


(integer variable) 
(string variable) 


(string array) 
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LANGUAGE SUMMARY 


Examples 


E(5,1) 
V8(3,3) 


1%(3.5) 
R2%(2,1) 


$$(8,5) 
V1$(4,2) 


BASIC-PLUS Language Summary 


A.2 SUMMARY OF OPERATORS 
Type Operator Operates Upon 


Arithmetic = Unary minus Numeric variables and constants 
Exponentiation 

Multiplication, division 

+,- Addition, subtraction 


* 
bie 


Relational Equals String or numeric variables and constants 
Less than 
Less than or equal to 
Greater than 
= Greater than or equal to 
> Not equal to 
= Approximately equal to 
(numbers) 
Identically equal to (strings) 


HO i” Sia A i 


Logical NOT Logical negation Relational expressions composed of 
AND Logical product string or numeric elements, integer vari- 
OR Logical sum ables or integer valued expressions 


XOR Logical exclusive or 
IMP Logical implication 
EQV Logical equivalence 


String + Concatenation String constants and variables 
Matrix +,- Addition and subtraction of Dimensioned variables. See Section 7.6.1 
matrices of equal dimen- for further details. 
sions, One operator per 
statement 
= Multiplication of con - 
formable matrices 
x Scalar multiplication of a 


matrix, see Section 7.6.1 


A.3 SUMMARY OF FUNCTIONS 
Under the Function column, the functions is shown as: 


Y=function 
where the characters % and $ are appended to Y if the value returned is an integer or character string. 
A floating value (X), where specified, can always be replaced by an integer value. An integer value (N%) can always 


be replaced by a floating value (an implied FIX is done) except in the CVT%$ and MAGTAPE functions (the symbol 
I% is used to indicate the necessity for an integer value). 
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(#9 


Type 


Mathematical 


Print 


String 
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Function 


Y=ABS(X) 
Y=ATN(X) 
Y=COS(X) 


Y=EXP(X) 


Y=FIX(X) 


Y=INT(X) 


Y=LOG(X) 


Y=LOG10(X) 


Y=PI 
Y=RND 


Y=RND(X) 
Y=SGN(X) 


Y=SIN(X) 
Y=SQR(X) 
Y=TAN(X) 


Y%=POS(X%) 


Y$=TAB(X%) 


Y%=ASCILK(A$) 


Y$=CHR$(X%) 


Y$=CVTZ%$ (1%) 


Y$=CVTF$(X) 


A-3 


Explanation 


Returns the absolute value of X. 
Returns the arctangent (in radians) of X. 


Returns the cosine of X where X is in 
radians. 


Returns the value of eX, where 
e=2.71828... 


Returns the truncated value of X, 
SGN(X)*INT(ABS(X)). 


Returns the greatest integer in X which is 
less than or equal to X. 


Returns the natural logarithm of X, 
log(e)X. 


Returns the common logarithm of X, 
log(10)X. 


Returns the constant 3.14159... 


Returns a random number between O 
and 1. 


Returns a random number between 0 
and 1. 


Returns the sign function of X;+ 1 if 
possible, 0 if zero, - 1 if negative. 


Returns the sine of X where X is in radians. 


Returns the square root of X. 


Returns the tangent of X where X is in 
radians. 


Returns the current position of the print 
head for I/O channel X%, O is the user’s 
Teletype. 


Moves print head to position X% in the 

current print record, or is disregarded if 
the current position is beyond X%. (The 
first position is counted as 0.) 


Returns the ASCII value of the first 
character in the string A$. 


Returns a character string having the 
ASCII value of X. Only one character is 
generated. 


Maps integer into 2-character string, see 
Section 12.5. 


Maps floating-point number into 4- or 8- 
character string, see Section 12.5. 


Type 


String 
cont'd. 
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Function 


Y%=CVT$%(AS) 


Y=CVT$F(A$) 


Y$=CVT$$(A$,1%) 


Y$=RAD$(N%) 


Y%=SWAPZH(N%) 


Y$=STRING$(N1%,N2%) 


Y$=LEFT(A$,N%) 


Y$=RIGHT(A$,N%) 


Y$=MID(A$,N1%,N2%) 


Y%=LEN(A$) 


Y%=INSTR(N1%,A$,B$) 


Y$=SPACES$(N%) 


Y$=NUMS(N%) 


Y$=NUM1S$(N) 


A-4 


Explanation 


Maps first two characters of string A$ into 
an integer, see Section 12.5. 


Maps first four or eight characters of 
string A$ into a floating-point number. 
See Section 12.5. 


Converts string A$ to string Y$ according 
to value of 1%. See Section 12.5. 


Converts an integer value to a 3- 
character string and is used to convert 
from Radix-50 format back to ASCII. 
See the RSTS/E Programming Manual.) 


Causes a byte swap operation on the two 
bytes in the integer variable N%. 


Creates string Y$ of length N1, composed 
of characters whose ASCII decimal value 
is N2. See Section 5.5. 


Returns a substring of the string A$ from 
the first character to the Nth character 
(the leftmost N characters). 


Returns a substring of the string A$ from 
the Nth to the last character; the rightmost 
characters of the string starting with the 
Nth character. 


Returns a substring of the string A$ start- 
ing with the N1 and being N2 characters 
long (the characters between and including 
the N1 to NI+N2-1 characters). 


Returns the number of characters in the 
string A$, including trailing blanks. 


Indicates a search for the substring B$ 
within the string A$ beginning at character 
position N1. Returns a value 0 if BS is not 
in A$, and the character position of B$ if 
B$ is found to be in A$ (character position 
is measured from the start of the string). 


Indicates a string of N spaces, used to 
insert spaces within a character string. 


Indicates a string of numeric characters 
representing the value of N as it would be 
output by a PRINT statement. For 
example: NUM$(1.0000) = (space) 1(space) 
and NUM$(- 1.0000) = - 1(space). 


Returns a string of characters representing 
the value of N. This is similar to the func- 
tion NUM$, except that it does not return 
spaces or E-format results. 


(ey 


Type 


String 
cont’d. 


System 
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Function 


Y=VAL(AS) 


X$=XLATE(AS,B$) 


Y$=SUM$(A$,B$) 


Y$=DIFF$(A$,B$) 


Y$=PRODS(A$,B$,P%) 


Y$=QUO$(A$,B$ ,P%) 


Y$=PLACE$(A$,P%) 


T%=COMP%(AS,BS$) 


Y$=DATE$(0%) 


Y$=DATES$(NZ) 


Y$=TIME$(0%) 


A-5 


Explanation 


Computes the numeric value of the string 
of numeric characters A$. If A$ contains 
any character not acceptable as numeric 
input with the INPUT statement, an error 
results. For example: 


VAL(“15”)=15 


Translate A$ to the new string Y$ by 
means of the table string BS. 


Returns a numeric string equal to the 
arithmetic sum of numeric strings A$ and 
BS. 


Returns a numeric string equal to the 
arithmetic difference A$-B$ of numeric 
strings A$ and B$. 


Returns a numeric string equal to the 
product of numeric strings AS and BS, 
rounded or truncated to P% places. 


Returns a numeric string equal to the 
arithmetic quotient A$/B$ of numeric 
strings A$ and B$, rounded or truncated 
to P% places. 


Returns a numeric string equal to the 
numeric string A, ronnded or truncated 
to P% places. 

Returns a value reflecting the result of an 
arithmetic comparison between numeric 
strings A$ and B$; T% =-1 for A<B, 0 for 
A=B and | for A>B. 


Returns the current date in the following 
format: 


02-Mar-71 
Returns a character string corresponding 
to a calendar date as follows: 
N=(day of year)+[(number of 
years since 1970)*1000] 
DATE$(1) = = ‘‘01-Jan-70” 
DATE$(125) = “05-May-70” 
Returns the current time of day asa 
character string as follows: 


TIME$(0)=*05:30 PM” 
on T7330 > 


BASIC-PLUS Language Summary 


Type Function Explanation 
System Y$=TIMES(NZ%) | Returns a string corresponding to the 
cont'd. time at N minutes before midnight. For 
example: 


TIMES(1)=“11:59 PM” 
OF 7st 


TIMES(1440)=12:00 AM”’ 
or G0-00: 

TIMES (72 1)=“11:59 AM” 
er tise 


Y=TIME(0%) Returns the clock time in seconds since 
midnight, as a floating-point number. 


Y=TIME(1%) Returns the central processor time used 
by the current job in tenths of seconds. 
Y=TIME(2%) Returns the connect time (during which 


the user is logged into the system) for 
the current job in minutes. 


Y=TIME(3%) Returns to Y the decimal number of kilo- 
core ticks (KCT’s) used by this job. 
See Section 8.8. 


Y=TIME(4%) Returns to Y the decimal number of 
minutes of device time used by this job. 
See Section 8.8. 


Y%=STATUS Returns to Y% the status of the OPEN 
statement executed most recently. See 
Section 12.3.5. 


Y%=BUFSIZ(N) Returns to Y% the buffer size of the 
device or file open on channel N. See 
Section 12.3.4. 


Y%=LINE Returns to Y% the line number of the 
statement being executed at the time of 
an interrupt. See Section 4.5. 


Y%=ERR Returns value associated with the last 
encountered error if an ON ERROR 
GOTO statement appears in the pro- 
gram. See Section 8.4. 


Y%=ERL Returns the line number at which the last 
error occurred if an ON ERROR GOTO 
statement appears in the program. See 
Section 8.4.3. 


Matrix MAT Y=TRN(X) Returns the transpose of the matrix X. 
See Section 7.6.2. 
MAT Y=INV(X) Returns the inverse of the matrix X. 


See Section 7.6.2. 
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Type Function Explanation 
Matrix 
cont'd. Y=DET Following an INV(X) function evaluation, 


the variable DET is equivalent to the 
determinant of X. 


Y %=NUM Following input of a matrix, NUM con- 
tains the number of rows input, or in the 
case of a 1-dimensional matrix, the 
number of elements entered. 


Y%=NUM2 Following input of a matrix, NUM2 
contains the number of elements entered 
in that row. 

Input/Output Y%=RECOUNT Returns the number of characters read 


following every input operation. Used 
primarily with non-file-structured 
devices. See Section 12.3.1. 


A.4 SUMMARY OF BASIC-PLUS STATEMENTS 

The following summary of statements available in the BASIC-PLUS language defines the general format for the state- 
ment as a line in a BASIC program. If more detailed information is needed, the reader is referred to the section(s) in 
the manual dealing with that particular statement. 


In these definitions, elements in angle brackets are necessary elements of the statement. Elements in square brackets 
are necessary elements of which the statement may contain one. Elements in braces are optional elements of the 


statement. 


The various elements and their abbreviations are described below: 


(# 


variable or var 
line number 
expression Or expr 
message 

condition or cond 


constant 


argument(s) or arg 
statement 
string 


protection 


value(s) 
list 


dimension(s) 


Any legal BASIC variable as described in A.1 or Section 2.5.2. 
Any legal BASIC line number described in Section 2.2. 

Any legal BASIC expression as described in Section 2.5. 

Any combination of characters. 

Any logical condition as described in Section 3.5. 


Any acceptable integer constant (need not contain a % 
character). 


Dummy variable names. 
Any legal BASIC-PLUS statement. 
Any legal string constant or variable as described in Section 5.1. 


Any legal protection code, as described in the RSTS/E System 
User's Guide. 


Any floating point, integer, or character string constant. 
The legal list for that particular statement. 


One or two dimensions of a matrix, the maximum dimension(s) 
for that particular statement. 
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Manual 
Statement Formats and Examples Section 
REM 
line number REM <message> a1 
line number <statement> !<message> 
100 REM THIS IS A COMMENT 
L110 | THIS IS ANOTHER FORM OF COMMENT 
120 PRINT | PERFORM A CR/LF 
LET 
line number {LET}<var> ,<var>,<var>... =<exp> 3.2 
110 LET AA = 404 \ B22 
ie CrFisV¥CQ) = O IMUL TIPLE ASSTGNMENT 
DIM 
line number DIM <var(dimension(s))> 3.6.2 
7.1 
30 DIM AC2ZO)» BEC S95)» CACHE) 
line number DIM #<constant>,<var(dimension(s))>=<constant> bist 
79 DIM #4» A$¢100) = Ses BCSOr50) 
RANDOMIZE 
line number RANDOMIZE 3.7.4 
ae RANTIOM 
LOO RANDOMIZE 
IF-THEN, IF-GOTO 
THEN<statement> 
line number IF <cond>| THEN<line number> 3.5 
GOTO<line number> 
te IF A=>B OR BeC THEN FRINT ’NO’ 
SS IF FNACRK) = B THEN 250 
70 IF Ll < X°2%- AND -L«>.0.. GOTO 349 
IF-THEN-ELSE | 
THEN<statement> | 
line number IF <cond>| THEN<line number> | areas ees 8.5 
GOTO<line number> pater suas | 
100 IF BR = A THEN FRINT “EQUAL ’ ELSE FRINT “NOT EQUAL’ 
L190 IF A == N THEN 200 ELSE FRINT A \ STOF 
bey IF FNACR) = B 


THEN GO TQ 240 
ELSE LET BR = BEFNACRI) 
ASA 3 eee 
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Manual 
Statement Formats and Examples Section 
FOR 
line number FOR <var> =<exp>TO<exp> | STEP<exp>} 335.0 
ZOO FOR I=2 TO 40 STEP 2 
320 FOR TH=0O% TO Tés% STEP IA 
Alo FOR N=A TO (C + S1)7A 
NEXT 
line number NEXT <var> 301 
4A&O NEXT I 
465 NEXT NA 
FOR-WHILE, FOR-UNTIL 8.6 
line number FOR <var> = <exp> STEP< Meas <cond> 
var> = <exp exp> UNTIL 
4l0 FOR I=1. STEP 3. WHILE I<x 
479 FOR NA = 2% STEP 4% UNTIL NASAA OR NA=BA 
JOO FOR B = 0. STEP EB+1. UNTIL B-Bl 
EXTEND 
line number EXTEND 
19 EXTEND IPFROGRAM IN EXTEND MODE Pe 
NO EXTEND 
line number NO EXTEND 
110 NOEXTENT M 
110 NO EXTEND 
DEF, single line ae 
line number DEF FN<var> (arg) = <exp(arg)> 55 
120 HEF ENACKs 32) = SGRCK 24. t. XO 2A +: 2 eRe 6.4 
DEF, multiple line 
line number DEF FN<var>(arg) 3:75 
<statements> we 
line number FN<var> = <exp> 6.4 
line number FNEND | 8.1 
300 NEF FNF CMA) IFACTORIAL FUNCTION 
310 IF M*Z=OZ%Z OR MA=12 


THEN FNF=124 
ELSE FNF=MAKFNF CMA-12) 
320 FNENT 
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Statement Formats and Examples 


GOTO 
line number GOTO <line number> 


LO0Q GOTO 150 


ON-GOTO 
line number ON <exp> GOTO <ilist of line numbers> 


150 ON XX GOTO 1709357094307 300 


GOSUB 
line number GOSUB <line number> 


1L?O GOSUB 2000 


ON-GOSUB 
line number ON <exp> GOSUB <iist of line numbers> 


230 ON FNCCM) GOSUB 2000924002 3000 


RETURN 
line number RETURN 


379 RE TURN 


CHANGE 


line number CHANGE |e) Pas 


TO = var> | 


<string var> <array name> 
i618) CHANGE A$ TO X 
45Q CHANGE Fi TO F1i¢ 


OPEN 
INPUT 
. . i 
line number OPEN<string> FOR ie AS FILE <exp> 


|, RECORDSIZE<exp>} {,CLUSTERSIZE<exp> | { MODE<exp>} 


100 OPEN “FF3’ FOR OUTFUT AS FILE B12 
120 OPEN “FOO’ AS FILE 3 
140 OPEN “OT4s0ATA. TR’ FOR INFUT AS FILE 10 


CLOSE 
line number CLOSE <list of exp> 


FBO CLOSE 224 
P20 CLOSE ill» 3y Ni 


Manual 
Section 


3.4 


8.2 


8.3 


5.2 


2 
| 


9.3 
RP 


BASIC-PLUS Language Summary 


Manual 
Statement Formats and Examples Section 
READ 3.3.1 
line number READ <list of variables> 313 
6.3 
Lio READ Ay Bs Flas BCIXZ)D Re 10.1 
DATA 3.3.1 
line number DATA <list of values> a3 
6.3 
L300 TATA 4-39 "STRING" » 10%1000%91,.45E9 
RESTORE 3.3.1 
line number RESTORE 10.2 
130 RES TORE 
PRINT 3.3.2 
line number PRINT }{#<exp>,{<list> 5.4 
6.3 
130 PRINT IGENERATES CR/LF 10.3 
170 PRINT “BEGINNING OF OUTFUT? “¢ Ts AxkT 10.3.1 
eAQ PRINT #49 “OUTFUT TO DEVICE ’sNZ 10.3.2 
2&O FRINT “TITLE? ‘FT#y “REF. #°9RS 
PRINT USING 
line number PRINT {#<exp>,}USING <string>, <list> 10.3.3 
AD FRINT USING ‘4. ##° » AA 
530 PRINT #7» USING BR¢yAv Bel 
INPUT 3.3.3 
line number INPUT |#<exp>,}<list> 5.3 
6.3 
L40 INFUT “TYPE YOUR NAME 7% sA% 10.4 
180 INFUT #8» AyNy BS 10.4.1 
INPUT LINE 5.3.1 
line number INPUT LINE {#<exp>,|<string> 
170 INFUT LINE R¢ 
L9YO INFUT LINE #1 °k% 
NAME-AS 
line number NAME <string> AS <string> 9.4 


455 NAME ‘NONAME’ AS ‘FILEL<48>/ 
290 NAME "DUT42MATRIX" AS ‘MATAL#48>/ 


BASIC-PLUS Language Summary 


Manual 
Statement Formats and Examples Section 
KILL 95 
line number KILL <string> 
LO KILL ’NONAME ’ 
ON ERROR GOTO 8.4 
line number ON ERROR GOTO 1 <line number> 
100 ON ERROR GOTO 9000 
110 ON ERROR GO TQ MNTISABLES ERROR ROUTINE 
ee ON ERROR GOTO 0O INISABLES ERROR ROUTINE 
RESUME 8.4.1] 
line number RESUME <line number> 
1000 RESUME FEQUIVALENT TO RESUME © 
HO RESUME 200 ISFECIFY RESUMFP TION FOINT 
CHAIN 
line number CHAIN <string> {<exp>} 9.6 
4AQ CHAIN “FROG? ’ 
he) CHAIN “FROGS3S’ 7S 
679 CHAIN "FROGS" A 
STOP 
line number STOP 3.9 
43Q STOF 
END 
line number END 3.9 
3276/7 E NII 
Matrix Statements 
MAT READ FP 
line number MAT READ <list of matrices> 
LO DIM AC2Z2O)» BE032)» CACLTSs190) 
270 MAT READ Avy BE¢25)% CA 
MAT PRINT 13 
line number MAT PRINT {#<exp>,} <matrix name> 10.3.4 
150 DIM AC2O) +» BACISs 30) 
190 MAT FRINT fy IFRINT 20 ELEMENTS FIVE TO A LINE 
wad MAT FRINT BAC10s25)3 IFRINT 10-BY~-25 SUBSET 
OF BAX» FACKED 
e?Q MAT FRINT tes As IFRINT ON OQUTFUT CHANNEL 2 
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Manual 
Statement Formats and Examples Section 
MAT INPUT 7.4 
line number MAT INPUT {#<exp>,} <list of matrices> 10.4.1 
1090 DIM BEC4O0)9 FIACSS) 
Lio OPEN “DTS:FOO’ FOR INPUT AS FILE 32% 
120 MAT INFUT #3» Bay Fila 
MAT Initialization dea 
ZER 
line number MAT <matrix name>= |CON |(dimension(s))} 
IDN 
mele DIM BCLS»10)»¥ AC1IO)» CACS) 
Lio MAT CZ = CON 
120 MAT B = ITDNC1IOr10) 
130 MAT BR = ZERCNs™M) 
Statement Modifiers (can be used in immediate mode) 
IF 8.7.1 
<statement> IF <condition> 
wi PRIM thr tarts 
UNLESS 
<statement> UNLESS <condition> Bitie 
340 FRINT A&® UNLESS YAiO4 
FOR 8.73 
<statement> FOR <var>=<exp> TO <exp> STEP <exp> 
iva Let BOtia?d = .C8Ciat FOR £4 = 14. 10: 392 
190 BEAD -ACI2Z) FOR 12-2 04 TO 202 STEP L352 
WHILE 8.7.4 
<statement> WHILE <condition> 
230 LET ACIZ) = FNXCIZ) WHILE A=45.5 
UNTIL 8.7.5 
<statement> UNTIL <condition> 
L060 IF B <> 0 THEN ACIZ) = B UNTIL I4% > K 
System Statements 
line number SLEEP <expression> 8.8 


240 SLEEF 20 INISMISS JOB FOR 20 SECONDS 
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Statement Formats and Examples 
line number WAIT <expression> 
wae Q WATT AA + SA 


Record I/O Statements 
line number LSET <string var> ,<string var> = <string> 


QO LSet 2S =.-“Xy¥Z" 
line number RSET <string var> ,<string var> = <string> 
asd RSET CS = *67890" 
line number FIELD# <expr>,<expr> AS <string var> ,<expr> AS <string var> 
210 FIELD #24» 104 AS Atty 20% AS BF 
line number GET# <expr> ,RECORD<expr> 
L40 GET #14 RECORD 992 
line number PUT# <expr> ,RECORD <expr> ,COUNT<expr> 


5FO FUT #ia» COUNT 802% 
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Manual 
Section 


8.8 


12.4.3 


12.4.2 


BES 


i233 


APPENDIX B 
BASIC-PLUS COMMAND SUMMARY 


This appendix describes briefly those RSTS/E commands used most frequently by BASIC-PLUS users. It is intended as 
an introductory summary; its purpose is to help BASIC-PLUS learners begin programming at the terminal before having 
studied the RSTS/E System User’s Guide in detail. 


Section in 
RSTS/E System 
Command Explanation User's Guide 
APPEND Used to include contents of a previously saved source program in 9.1.4 
current program. 
ASSIGN Used to reserve an I/O device for the use of the individual issuing the nee | 
command. The specified device can then be given commands only 5.4 
from the job which issued the ASSIGN. Also establishes a logical name 6.1 
for a device, establishes an account for the @ character, and establishes 
a default protection code. 
ATTACH Attaches a detached job to the current terminal. 14.1] 
BYE Indicates to RSTS/E that a user wishes to leave the terminal. Closes ee 
and saves any files remaining open for that user. 
After the user types BYE, the system responds: 
Confirm: 
At this point the user has five options: 
? Requests information on valid responses to the 
“Confirm” prompt. 
Y — Requests normal logout. 
N Requests no logout; effectively negates the BYE 
command. 
I Requests an opportunity to delete files 
individually prior to logout. 
F Fast logout. 
If BYE is followed immediately with one of the valid responses, the 
“Confirm” prompt is not printed. 
CAT Returns the user’s file directory. Unless another device is specified 8.9 
CATALOG following the term CAT or CATALOG, the disk is the assumed device. 
CCONT For privileged users. Same as CONT command, but detaches job from 10.2.3 
terminal. 
COMPILE Allows the user to store a compiled version of his BASIC program. The 8.4.3 


file is stored on disk with the current name and the extension .BAC. Or, 
a new file name can be indicated and the extension .BAC will still be 
appended. 
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Command 


CONT 


DEASSIGN 


DELETE 


EXTEND 


HELLO 


KEY 


LENGTH 


LIST 


LISTNH 


LOGIN 


BASIC-PLUS Command Summary 


Explanation 


Allows the user to continue execution of the program 
currently in memory following the execution of a STOP 
statement. 


Used to release the specified device for use by others. If no 
particular device is specified, all devices assigned to that terminal 


are released. An automatic DEASSIGN is performed when the BYE 


command is given. Also releases any logical name for a device. 


Allows the user to remove one or more lines from the program 
currently in memory. Following the word DELETE the user 
types the line number of the single line to be deleted or two line 
numbers separated by a dash (—) indicating the first and last line 
of the section of code to be removed. Several single lines or line 
sections can be indicated by separating the line numbers, or 

line number pairs, with a comma. 


Allows the user to include Extend Mode features in programs 
and to execute programs that include Extend Mode features. 
The system default is No Extend Mode following log-in, and 
remains so until an EXTEND command changes mode. Either 
mode condition can be overridden at the program level. 


Indicates to RSTS/E that a user wishes to log onto the system. 
Allows the user to input project-programmer number and pass- 
word. Also attaches a detached job to the current terminal or 
changes accounts without having to log off the system 


Used to re-enable the echo feature on the user terminal 
following the issue of a TAPE command. Enter with LINE 
FEED or ESCAPE key. 


Returns the length of the user’s current program in core, in 1K 
increments, along with the maximum size. If the current program 
is between 6K and 7K, for instance, and the maximum size is 
16K, the following message appears: 


7(16)K of memory used 


Allows the user to obtain a printed listing at the user terminal of 
the program currently in memory, or one or more lines of that 
program. The word LIST by itself will cause the listing of the 
entire user program. LIST followed by one line number will list 
that line; and LIST followed by two line numbers separated by 

a dash (—) will list the lines between and including the lines 
indicated. Several single lines or line sections can be indicated by 
separating the line numbers, or line number pairs, with a comma. 


Same as LIST, but does not print header containing the program 
name and current data. 


Same as HELLO. 
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Section in 
RSTS/E System 
User’s Guide 


10.2.2 


Dee 
5.4.3 
5.4.4 

7 


ae 


P24 


és 
14.1.1 


Sud 


8.8 


O44 


14.1.1 


Command 


MOUNT 


NEW 


NO EXTEND 


OLD 


REASSIGN 
RENAME 


REPLACE 


RUN 


RUNNH 


BASIC-PLUS Command Summary 


Explanation 


Allows user to logically mount a disk pack during timesharing. 
This command specifies the physical device name and pack 
identification label. 


Clears the user’s area in memory and allows the user to input a 
new program from the terminal. A program name can be indicated 
following word NEW or when the system requests it. 


Negates any previous EXTEND command, placing the system 
default in No Extend Mode. Extend Mode features are no longer 
available unless the program includes an EXTEND statement to 
override system default. 


Clears the user’s area in memory and allows the user to recall a 
saved program from a storage device. The user can indicate a 
program name following the word OLD or when the system 
requests it. If no device name is given, the file is assumed to be on 
the public structure. A device specification without a filename 
will cause a program to be read from an input-only device (such 
as high-speed reader, card reader). The default filename extension 
is .BAS. 


Transfers control of a device to another job. 


Causes the name of the program currently in memory to be changed 
to the name specified after the word RENAME. 


Same as SAVE, but allows the user to substitute a new program 
for an old program with the same name, erasing the old program. 


Allows the user to begin execution of the program currently in 
memory. The word RUN can be followed by a filename in which 
case the file is loaded from the public structure, compiled (if 
necessary ), and run; alternatively, the device and filename can be 
indicated if the file is not on the public structure. A device 
specification without a filename will cause a program to be read 
from an input only device (such as high-speed reader, card 
reader). The default filename extension is .BAS. 


Causes execution of the program currently in memory but header 
information containing in program name and current data is not 
printed. If a filename is used, the command is executed as if no 
filename were given. The default filename extension is .BAS. 
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Section in 
RSTS/E System 
User’s Guide 


5.6.11 


BE 


8.3 


Pe 
8.5 


8.6 


8.4 


8.4 


BASIC-PLUS Command Summary 


Section in 
RSTS/E System 
Command Explanation User’s Guide 
SAVE Causes the program currently in memory to be saved on the public 8.2 
structure under its current filename with the extension .BAS. 
Where the word SAVE is followed by a filename or a device 
and a filename, the program in memory is saved under the name 
given and on the device specified. A device specification without 
a filename will cause the program to be output to any output 
only device (line printer, high-speed punch). The default filename 
extension is .BAS. 
SCALE Sets the scale factor to a designated value or prints the value(s) 8.10 
currently in effect if no value is designated. 
TAPE Used to disable the echo feature on the user terminal while reading 5.8.1 
paper tape via the low-speed reader. 
UNSAVE The word UNSAVE is followed by the filename, and optionally, 
the extension of the file to be removed. The UNSAVE command 
cannot remove files without an extension. If no extension is 
specified, the source (.BAS) file is deleted. If no device is 
specified, the public structure is assumed. 
Special Control Character Summary 
CTRL/C Causes the system to return to BASIC command mode to allow 5.9.1 
for issuing of further commands or editing. Echoes on terminal as 10.3 
si 
CTRL/O Used as a switch to suppress/enable output of a program on the 592 
user terminal. Echoes as “O. 10.3 
CTRL/Q When generated by a device on which a CTRL/S has interrupted 593 
output, causes computer to resume output at the next character. 
CTRL/S When generated by a device for which STALL characteristics oe Pe, 
are set, interrupts computer output on the device until either 
CTRL/Q or another character is generated. 
CTRL/U Deletes the current typed line, echoes as ~“U and performs a Bae 
carriage return/line feed. 
CTRL/Z Used as an end-of-file character. 5.9.4 
ESCape or Enters a typed line to the system, echoes on the user terminal as 5.9.6 
ALT MODE a $ character and does not cause a carriage return/line feed. 
Key 
LINE FEED Used to continue the current logical line on an additional PE BPE: 
Key physical line. Performs a line feed/carriage return operation. 
RETURN Enters a typed line to the system, results in a carriage return/line 5.9.5 
Key feed operation at the user terminal. 
RUBOUT Deletes the last character typed on that physical line. Erased 94351 
Key characters are shown on the teleprinter between backslashes. 
TAB or Performs a tabulation to the next tab stop (eight spaces apart) of S223 
CTRL/I the terminal printing line. 
FORM FEED Enters a typed line to the system, results in a form feed operation 
or CTRL/L at the terminal. 
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APPENDIX C 
ERROR MESSAGES 


Messages in RSTS/E are generated for BASIC-PLUS errors! and RSTS/E errors. To avoid confusion, both types of 
messages are called RSTS/E error messages and are described as one set. The BASIC-PLUS errors cover compiler and 
run time conditions such as a violation of the syntax rules (SYNTAX ERROR) and referencing an element of an 
array beyond the defined limits (SUBSCRIPT OUT OF RANGE). The RSTS/E errors involve operating system con- 
ditions such as failing to locate the file or account specified (CAN’T FIND FILE OR ACCOUNT) and requesting the 
hardware to perform a function for which it is not ready (DEVICE HUNG OR WRITE LOCKED). 


In most cases, if no error trapping is being done (that is,an ON ERROR GOTO statement is not in effect), BASIC- 
PLUS stops running the program. It prints the error message and the line number of the BASIC-PLUS statement that 
was being executed when the error occurred. The following sample printout shows the procedure. 


10 OPEN “Z* POR INPUT AS FICE 1x 
RUNNH 
PCAN‘ST FINI FILE OR ACCOUNT AT LINE 10 


REALTY 
As the READY message indicates, control returns to the system. 


An exception to this procedure occurs when an INPUT statement is being executed at the job’s console terminal 
and error trapping is not in effect. The system generates the error message and executes the statement again as shown 
in the sample printout below. 


10 ON ERROR GOTO O \ INFUT “INTEGER VALUE’ ¢ AZ 
RUNNH 

INTEGER VALUE? C 

AUATA FORMAT ERROR AT LINE 10 

INTEGER VALUE? 


With error trapping disabled at line 10, an invalid response to the INPUT statement causes the system to print the 
error message, clear the error condition, and execute the statement again. 


Associated with each message is an error variable called ERR. Whenever an error occurs with trapping in effect, the 
system checks the error variable which is a decimal number in the range 0 to 127. An error with a number between 

1 and 70 causes the system to transfer control to the line number indicated in the ON ERROR GOTO statement. 
The system does not print the error message. The user program is able to check the ERR variable and perform a 
recovery procedure. If the error number is between 71 and 127, the system does not transfer control to the recovery 
routine but prints the message and returns control to the system. (Error number 0 is reserved to identify the system 
installation name.) 


Because a BASIC-PLUS program can recover from certain errors, this appendix lists errors in two categories — re- 
coverable and non-recoverable. The recoverable error messages are listed in ascending order of their related error 
numbers. A program can use these error numbers to differentiate errors. Non-recoverable errors are in alphabetical 
order without error numbers because a program can not use these numbers in an error handling routine. 


I Different messages are generated while a job is operating under run-time systems other than BASIC-PLUS. Such run-time systems 
are those for COBOL and FORTRAN-IV. For these error messages, consult the appropriate User’s Guides. 
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Error Messages 


The first character position of each.message indicates the severity of the error. Table C-1 describes this standard. 


Table C-1 Severity Standard in Error Messages 


Execution of the program can continue but 
may not generate the expected results. 


Execution cannot continue unless the user 
removes the cause of the error. 


Information A message beginning with neither a question 
mark nor a percent is for information only. 


The severity indication is useful for utility programs such as BATCH which examines system output. 


In the descriptions of error messages, certain abbreviations, as shown in Table C-2, denote special characteristics of 
the error. 


Table C-2 Special Abbreviations for Error Descriptions 


(C) Continue. If an ON ERROR GOTO statement is not in effect, 
(SPR) 


execution continues but with the conditions described. 


Software Performance Report. This error should occur only under 
the conditions described. If it occurs under any other conditions, 

the user should file an SPR with DIGITAL and document the con- 
ditions under which the error occurred. 


An error whose description is accompanied by the abbreviation (C) indicates an exception to the error trapping pro- 


cedure. If suchan error occurs in a program with no error trapping in effect, BASIC-PLUS prints the error message 
and line number but continues running the program. The following sample printout shows the procedure. 


100 ON ERROR GOTO O \ AZ = 32768. 
200 FRINT AZ 

RUNNH 

AINTEGER ERROR AT LINE 100 

O 


READY 


The INTEGER ERROR is generated at line 100 by the attempt to compute a value outside the range for integers. 


After the error message is printed, processing continues but with the conditions described in the error meaning. 0 is 


substituted for the erroneously computed value. 


The number of RSTS/E error messages is restricted to 127. Because of this restriction, certain error messages have 
multiple meanings. The specific meaning of an error message depends on the operation being performed when the 
error condition occurs. For example, if the system attempts a file access and the designated file can not be located, 
RSTS/E generates the CAN’T FIND FILE OR ACCOUNT error (ERR=5). That same error condition, however, 
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e 


Error Messages 


applies to other, generically similar access operations. Thus, if a program attempts to send a message to another 
program and the proper entry is not found in the system table of eligible receivers, RSTS/E returns error number 
5. Though the second failure does not involve a file access error, it too is classified as an access failure. 


Certain RSTS/E errors, although classified as user recoverable, are not capable of being trapped by a program. 
Table C-3 lists such errors. 


Table C-3 Non-Trappable Errors in Recoverable Class 


a BRR Message Printed 


RESERVED INSTRUCTION TRAP 


SP (R6) STACK OVERFLOW 


DISK ERROR DURING SWAP 


MEMORY PARITY FAILURE 


These errors involve special conditions which a user program cannot control and which ought not to occur ona 
normal system. For example, the DISK ERROR DURING SWAP error indicates a hardware problem. The system 
does not return control to the program. The error condition itself, however, can be either transient or recurring. 
Such errors should be brought to the attention of the system manager for further investigation. These errors are 
recoverable in the strict sense that the monitor can take corrective action but the BASIC-PLUS run-time system 
does not return control to the user program. 


C.1 USER RECOVERABLE 
ERR Message Printed Meaning 


0 (system installation name) The error code 0 is associated with the system installation name and 
is used by system programs to print identification lines. 


| ?Bad directory for device The directory of the device referenced is in an unreadable format. The 
magtape label format on tape differs from the system-wide default 
format, the current job default format, or the format specified in the 
OPEN statement. Use the ASSIGN command to set the correct format 
default or change the format specification in the MODE option of the 
OPEN statement. 


2 ?Illegal file name The filename specified is not acceptable. It contains unacceptable char- 
acters or the filename specification format has been violated. The CCL 
command to be added begins with a number or contains a character 
other than A through Z, 0 through 9 and commercial at (@). 


3 ? Account or device in use Reassigning or dismounting of the device cannot be done because the 
device is open or has one or more open files. The account to be de- 
leted has one or more files and must be zeroed before being deleted. 
The run time system to be deleted is currently loaded in memory and 
in use. Output to a pseudo keyboard cannot be done unless the device 
is in KB wait state. An echo control field cannot be declared while 
another field is currently active. The CCL command to be added al- 
ready exists. 
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10 


1] 


12 


13 


14 


16 


Message Printed 


?No room for user on device 


?Can’t find file or account 


?Not a valid device 


?1/O channel already open 


?Device not available 


?1/O channel not open 


?Protection violation 


?End of file on device 


?Fatal system I/O failure 


?User data error on device 


?Device hung or write locked 


?Keyboard WAIT exhausted 


?Name or account now exists 


Error Messages 


Meaning 


Storage space allowed for the current user on the device specified has 
been used or the device as a whole is too full to accept further data. 


The file or account number specified was not found on the device 
specified. The CCL command to be deleted does not exist. 


The device specification supplied is not valid for one of the following 
reasons. The unit number or its type is not configured on the system. 
The specification is logical and untranslatable because a physical device 
is not associated with it. 


An attempt was made to open one of the twelve I/O channels which 
had already been opened by the program. (SPR) 


The specified device exists on the system but a user’s attempt to 
ASSIGN or OPEN it is prohibited for one of the following reasons. 

The device is currently reserved by another job. The device requires 
privileges for ownership and the user does not have privilege. The device 
or its controller has been disabled by the system manager. The device 

is a keyboard line for pseudo keyboard use only. 


Attempt to perform I/O on one of the twelve channels which has not 
been previously opened in the program. 


The user was prohibited from performing the requested operation be- 
cause the kind of operation was illegal (such as input from a line print- 
er) or because the user did not have the privileges necessary (such as 
deleting a protected file). 


Attempt to perform input beyond the end of a data file; or a BASIC 
source file is called into memory and is found to contain no END 
statement. 


An I/O error has occurred on the system level. The user has no guaran- 
tee that the last operation has been performed. This error is caused by 
hardware condition. Report such occurrences to the system manager. 
(See the discussion at beginning of appendix.) 


One or more characters may have been transmitted incorrectly due to 
a parity error, bad punch combination on a card, or similar error. 


User should check hardware condition of device requested. Possible 
causes of this error include a line printer out of paper or high-speed 
reader being off-line. 


Time requested by WAIT statement has been exhausted with no input 
received from the specified keyboard. 


An attempt was made to rename a file with the name of a file which 


already exists, or an attempt was made by the system manager to in- 
sert an account number which is already within the system. 
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22 


23 


24 


25 


26 


27 


28 


29 


30 


31 


32 


Message Printed 


?Too many open files on unit 


?Ilegal SYS(_) usage 


?Disk block is interlocked 


?Pack IDs don’t match 


?Disk pack is not mounted 
?Disk pack is locked out 


Illegal cluster size 


?Disk pack is private 
?Disk pack needs ‘CLEANing’ 
?Fatal disk pack mount error 


21/0 to detached keyboard 


?Programmable +C trap 


?Corrupted file structure 


?Device not file structured 


?Illegal byte count for I/O 


2No buffer space available 


Error Messages 


Meaning 


Only one open DECtape output file is permitted per DECtape drive. 
Only one open file per magtape drive is permitted. 


Illegal use of the SYS system function. 


The requested disk block segment is already in use (locked) by some 
other user. 


The identification code for the specified disk pack does not match the 
identification code already on the pack. 


No disk pack is mounted on the specified disk drive. 
The disk pack specified is mounted but temporarily disabled. 


The specified cluster size is unacceptable. The cluster size must be a 
power of 2. For a file cluster, the size must be equal to or greater than 
the pack cluster size and must not be greater than 256. For a pack 
cluster, the size must be equal to or greater than the device cluster size 
and must not be greater than 16. The device cluster size is fixed by type. 


The current user does not have access to the specified private disk pack. 
Non-fatal disk mounting error; use the CLEAN operation in UTILTY. 
Fatal disk mountmg error. Disk cannot be successfully mounted. 


I/O was attempted to a hung up dataset or to the previous, but now 
detached, console keyboard for the job. 


A CTRL/C combination was typed while an ON ERROR GOTO state- 
ment was in effect and programmable CTRL/C trapping was enabled. 


Fatal error in CLEAN operation. 


An attempt is made to access a device, other than a disk, DECtape, or 
magtape device, as a file-structured device. This error occurs, for ex- 
ample, when the user attempts to gain a directory listing of a non- 
directory device. 


The buffer size specified in the RECORDSIZE option of the OPEN 
statement or in the COUNT option of the PUT statement is not a multi- 
ple of the block size of the device being used for I/O, or is illegal for the 
device. An attempt is made to run a compiled file which has improper 
size due to incorrect transfer procedure. 


The user accesses a file and the monitor requires one small buffer to 
complete the request but one is not currently available. If the program 
is sending messages, two conditions are possible. The first occurs when 
a program sends a message and the receiving program has exceeded the 
pending message limit. The second occurs when a sending program 
attempts to send a message and a small buffer is not available for the 
operation. 
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33 


34 
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36 


37 


38 


39 


40 


41 


42 


43 


45 


46 


47 


48 


Message Printed 


?UNIBUS timeout fatal trap 


? Reserved instruction trap 


?Memory management violation 


?SP (R6) stack overflow 


?Disk error during swap 


?Memory parity failure 


?Magtape select error 


?Magtape record length error 


?Non-res run-time system 


?Virtual buffer too large 


?Virtual array not on disk 


?Matrix or array too big 


?Virtual array not yet open 


Illegal I/O channel 


?Line too long 


%Floating point error 


Error Messages 


Meaning 


This hardware error occurs when an attempt is made to address non- 
existent memory or an odd address using the PEEK function. An 
occurrence of this error message in any other case is cause for an SPR. 


An attempt is made to execute an illegal or reserved instruction or an 
FPP instruction when floating point hardware is not available. (See 
discussion at beginning of appendix.) 


This hardware error occurs when an illegal Monitor address is specified 
using the PEEK function. Generation of the error message in situations 
other than using PEEK is cause for an SPR. 


An attempt to extend the hardware stack beyond its legal size is en- 
countered. (See discussion at beginning of appendix.) (SPR) 


A hardware error occurs when a user’s job is swapped into or out of 
memory. The contents of the user’s job area are lost but the job re- 
mains logged into the system and is reinitialized to run the NONAME 
program. Report such occurrences to the system manager. (See dis- 
cussion at beginning of appendix.) 


A parity error was detected in the memory occupied by this job. (See 
discussion at beginning of appendix.) 


When access to a magtape drive was attempted, the selected unit was 
found to be off line. 


When performing input from magtape, the record on magtape was 
found to be longer than the buffer designated to handle the record. 


The run time system referenced has not been loaded into memory and 
is therefore non-resident. 


Virtual core buffers must be 512 bytes long. 


A non-disk device is open on the channel upon which the virtual array 
is referenced. 


_ In-core array size is too large. 


An attempt was made to use a virtual array before opening the corre- 
sponding disk file. 


Attempt was made to open a file on an I/O channel outside the range 
of the integer numbers | to 12. 


Attempt to input a line longer than 255 characters (which includes 
any line terminator ). Buffer overflows. 


Attempt to use a computed floating point number outside the range 


1E-38 <n<1E38 excluding zero. If no transfer to an error handling 
routine is made, zero is returned as the floating point value. (C) 
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50 


51 
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53 


54 


2 


56 


$7 


58 


59 


60 


61 


62 


63 


64 


Message Printed 


% Argument too large in EXP 


%Data format error 


Ylnteger error 


Illegal number 


%lllegal argument in LOG 


YImaginary square roots 


?Subscript out of range 


?Can’t invert matrix 
?Out of data 


2ON statement out of range 


?Not enough data in record 


?Integer overflow, FOR loop 


%Division by 0 


?No run-time system 


?FIELD overflows buffer 


Not a random access device 


Error Messages 


Meaning 


Acceptable arguments are within the approximate range - 89<arg<+88. 
The value returned is zero. (C) 


A READ or INPUT statement detected data in an illegal format. For 
example, 1..2 is an improperly formed number, and 1.3 is an improp- 
erly formed integer, and X” is an illegal string. (C) 


Attempt to use a computed integer outside the range -32768<n<32767. 
For example, an attempt is made to assign to an integer variable a 
floating point number outside the integer range. If no transfer to an 
error handling routine is made, zero is returned as the integer value. (C) 


Integer overflow or underflow or floating point overflow. The range 

for integers is - 32768 to +32767; for floating point numbers, the upper 
limit is 1E38. (For floating point underflow, the FLOATING POINT 
ERROR (ERR=48) is generated.) 


Negative or zero argument to LOG function. Value returned is the 
argument as passed to the function. (C) 


Attempt to take square root of a number less than zero, The value re- 
turned is the square root of the absolute value of the argument. (C) 


Attempt to reference an array element beyond the number of elements 
created for the array when it was dimensioned. 


Attempt to invert a singular or nearly singular matrix. 
The DATA list was exhausted and a READ requested additional data. 


The index value in an ON-GOTO or ON-GOSUB statement is less 
than one or greater than the number of line numbers in the list. 


An INPUT statement did not find enough data in one line to satisfy 
all the specified variables. 


The integer index in a FOR loop attempted to go beyond 32766 or 
below - 32767. 


Attempt by the user rrugram to divide some quantity by zero. If no 
transfer is made to an error handler routine, a O is returned as the re- 


sult. (C) 


The run-time system referenced has not been added to the system list 
of run time systems. 


Attempt to use FIELD to allocate more space than exists in the speci- 
fied buffer. 


Attempt to perform random access I/O to a non-random access device. 
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ERR Message Printed 
65 ?Illegal MAGTAPE ( ) usage 


66 ?Missing special feature 


67 Illegal switch usage 


C.2 NON-RECOVERABLE 
Message Printed 


?Arguments don’t match 


?Bad line number pair 


?Bad number in PRINT-USING 


?Can’t compile statement 


?Can’t CONTinue 


?Data type error 


?DEF without FNEND 


2End of statement not seen 


?Execute only file 


?Expression too complicated 


?File exists-RENAME/REPLACE 


?FNEND without DEF 


Error Messages 


Meaning 
Improper use of the MAGTAPE function. 


User program employs a BASIC-PLUS feature not present on the 
given installation. 


A CCL command contains an error in an otherwise valid CCL switch. 
(For example, the /SI:n switch was used without a value for n or a 
colon; or more than one of the same type of CCL switch was speci- 
fied.) A file specification switch is not the last element in a file speci- 
fication or is missing a colon or an argument. 


Meaning 


Arguments in a function call do not match, in number or in type, the argu- 
ments defined for the function. 


Line numbers specified in a LIST or DELETE command were formatted 
incorrectly. 


Format specified in the PRINT-USING string cannot be used to print one or 
more values. 


Program was stopped or ended at a spot from which execution cannot be 
resumed. 


Incorrect usage of floating-point, integer, or character string format variable 
or constant where some other data type was necessary. 


A second DEF statement was encountered in the processing of a user func- 
tion without an FNEND statement terminating the first user function def- 
inition. 

Statement contains too many elements to be processed correctly. 


Attempt was made to add, delete or list a statement in a compiled (.BAC) 
format file. 


This error usually occurs when parentheses have been nested too deeply. The 
depth allowable is dependent on the individual expression. 


A file of the name specified in a SAVE command already exists. In order to 
save the current program under the name specified, use REPLACE, or use 


RENAME followed by SAVE. 


An FNEND statement was encountered in the user program without a pre- 
vious function call having been executed. 
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Message Printed 


?FNEND without function call 


2FOR without NEXT 


?Illegal conditional clause 


Illegal DEF nesting 


?Illegal dummy variable 


— Mllegal expression 


Illegal FIELD variable 
Illegal FN redefinition 


?Illegal function name 


?Illegal IF statement 


?Illegal in immediate mode 


?Illegal line number(s) 
?Illegal mode mixing 


Illegal statement 


Illegal symbol 


Illegal verb 


%Inconsistent function usage 


ZInconsistent subscript use 


x(y)K of memory used 


Error Messages 


Meaning 


A FNEND statement was encountered in the user program without a pre- 
vious DEF statement being seen. 


A FOR statement was encountered in the user program without a correspond- 
ing NEXT statement to terminate the loop. 


Incorrectly formatted conditional expression. 


The range of one function definition crosses the range of another function 
definition. 


One of the variables in the dummy variable list of user-defined function is 
not a legal variable name. 


Double operators, missing operators, mismatched parentheses, or some sim- 
ilar error has been found in an expression. 


The FIELD variable specified is unacceptable. 
Attempt was made to redefine a user function. 


Attempt was made to define a function with a function name not sub- 
scribing to the established format. 


Incorrectly formatted IF statement. 


User issued a statement for execution in immediate mode which can only be 
performed as part of a program. 


Line number reference outside the range 1<n<32767. 
String and numeric operations cannot be mixed. 


Attempt was made to execute a statement that did not compile without 
errors. 


An unrecognizable character was encountered. For example, a line consisting 
of a #character. 


The BASIC verb portion of the statement cannot be recognized. 


A function is defined with a certain number of arguments but is elsewhere 
referenced with a different number of arguments. Fix the reference to match 
the definition and reload the program to reset the function definition. 


A subscripted variable is being used with a different number of dimensions 
from the number with which it was originally defined. 


Message printed by the LENGTH command. The value for x is the current 
size, to the nearest 1K-word increment, of the program in memory. The val- 
ue for y is the size to which the program can expand, given the run time 
system being used and the job’s private memory size maximum set by the 
system manager. 
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Message Printed 
? Literal string needed 


?Matrix dimension error 


?Matrix or array without DIM 


?Maximum memory exceeded 


?Modifier error 


? NEXT without FOR 


?No logins 


?Not enough available memory 


?Number is needed 
?1 or 2 dimensions only 
20N statement needs GOTO 


Please say HELLO 


?Please use the RUN command 


2?PRINT-USING buffer overflow 


?PRINT-USING format error 


?Program lost-Sorry 


Error Messages 


Meaning 


A variable name was used where a numeric or character string was necessary. 


Attempt was made to dimension a matrix to more than two dimensions, or 
an error was made in the syntax of a DIM statement. 


A matrix or array element was referenced beyond the range of an implicitly 
dimensioned matrix. 


During an OLD operation, the job’s private memory size maximum was 
reached. While running a program, the system required more memory for 
string or I/O buffer space and the job’s private memory size maximum or 
the system maximum (16K words for BASIC-PLUS) was reached. 


Attempt to use one of the statement modifiers (FOR, WHILE, UNTIL, IF, 
or UNLESS) incorrectly. An OPEN statement modifier, such as a RECORD- 
SIZE, CLUSTERSIZE, FILESIZE, or MODE option, is not in the correct 
order. 


A NEXT statement was encountered in the user program without a previous 
FOR statement having been seen. 


Message printed if the system is full and cannot accept additional users or if 
further logins are disabled by the system manager. 


An attempt is made to load a non-privileged compiled program which is too 
large to run, given the job’s private memory size maximum. The program 
must be made privileged to allow it to expand above a private memory size 
maximum; or the system manager must increase the job’s private memory 
size maximum to accommodate the program. 


A character string or variable name was used where a number was necessary. 


Attempt was made to dimension a matrix to mofe than two dimensions. 


A statement beginning with ON does not contain a GOTO or GOSUB clause. 


Message printed by the LOGIN system program. User not logged into the 
system has typed something other than a legal, logged-out command to the 
system. 


A transfer of control (as ina GOTO, GOSUB or IF-GOTO statement) cannot 


be performed from immediate mode. 


Format specified contains a field too large to be manipulated by the PRINT- 


USING statement. 


An error was made in the construction of the string used to supply the out- 
put format in a PRINT-USING statement. 


A fatal system error has occurred which caused the user program to be lost. 
This error can indicate hardware problems or use of an improperly compiled 
program. Consult the system manager or the discussion of such errors in the 
RSTS/E System Manager’s Guide. 
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Message Printed 


?Redimensioned array 


?RESUME and no error 


2?RETURN without GOSUB 


%SCALE factor interlock 


?Statement not found 


Stop 


?String is needed 
?Syntax error 


?Too few arguments 


?Too many arguments 


?Undefined function called 


?What? 


?Wrong math package 


Error Messages 


Meaning 


Usage of an array or matrix within the user program has caused BASIC-PLUS 
to redimension the array implicitly. 


A RESUME statement was encountered where no error had occurred to 
cause a transfer into an error handling routine via the ON ERROR GOTO 
statement. 


RETURN statement encountered in user program without a previous 
GOSUB statement having been executed. 


An attempt was made to execute a program or source statement with the 
current scale factor. The program runs but the system uses the scale factor 
of the program in memory rather than the current scale factor. Use 
REPLACE and OLD or recompile the program to run with the current 
scale factor. (C) 


Reference is made within the program to a line number which is not within 
the program. 


STOP statement was executed. The user can usually continue program exe- 
cution by typing CONT and the RETURN key. 


A number or variable name was used where a character string was necessary. 
BASIC-PLUS statement was incorrectly formatted. 


The function has been called with a number of arguments not equal to the 
number defined for the function. 


A user-defined function may have up to five arguments. 


BASIC-PLUS interpreted some statement component as a function call for 
which there is no defined function (system or user). 


Command or immediate mode statement entered to BASIC-PLUS could not 
be processed. Illegal verb or improper format error most likely. 


Program was compiled on a system with either the 2-word or 4-word math 
package and an attempt is made to run the program on a system with the 
opposite math package. Recompile the program using the math package of 
the system on which it will be run. 


\ ’ ua 
i mi 
\ ¥ lie 
m us st 
i) r) \ 
‘ ’ ¥ 
‘ < 
t ; } 
¢ * 4 , 
4 
; de a 
B) tA \ 
; ‘ 
Y A 
4 nes | # Faby 
‘ nM 
1), j 4 
' ‘ 
ty 
yi 
y a} 


‘ ‘ 
¥ b 
5 a ; 
i ‘ 
, 1 u 
he ( ’ 
om 
? 
Me 
‘ 
ay 
r * bd 
Ha 
va A 
. het} 
, 


APPENDIX D 
BASIC-PLUS CHARACTER SET 


User program statements are composed of individual characters. Allowable characters come from the following 


character set: 


1. A through Z 


2. O through 9 


3. Space 
4. Tab 


and the following special symbols and keys: 


Key 


$ 


Use and Section in BASIC-PLUS Language Manual 


Used in specifying string values (Chapter 5), or as the System Library file designator (RSTS/E System 
User’s Guide). 


Used in specifying integer values (Chapter 6). Also denotes account [1,4]. 
Used to delimit string constants, i.e., text strings (Chapter 5). 
Begins comment part of a line (Section 3.1). Also denotes account [1,3]. 


Separates multiple statements on one line (Section 2.4.1). The colon is accepted for compatibility with 
previous versions. 


Denotes a device or file channel number, or is used as an output format effector (Chapter 10). Also 
denotes account number using current project number with a programmer number of 0. 


Output format effector and list terminator (Section 3.3.2). 
Output format effector (Section 3.3.2). 


If EXTEND Mode is in effect, can be used at the end of a line to indicate that the current statement is 
continued on the next line. Denotes account [1,5]. 


Denotes the assignable account. 


When used at the end of a line, indicates that the current statement is continued on the next line 
(Section 2.4.2). 


Valid variable-name character in Extend Mode. Also used in graphic representations of floating point 
numbers and strings to denote a decimal point. Delimits filename extensions. 


Used to group arguments in an arithmetic expression (Section 2.6.3), or to delimit project-programmer 
number. 


Used to group project-programmer number. Equivalent to ( ). 
Used to delimit file protection codes. 


Arithmetic operators (Section 2.6.3). 
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BASIC-PLUS Character Set 


Key Use and Section in BASIC-PLUS Language Manual 


Replacement operator (Section 3.2). Relational equivalence operator (Section 2.6.4 and 5.1.5). 
Logical “‘less than” operator (Sections 2.6.4 and 5.1.5). 
Logical “‘greater than” operator (Sections 2.6.4 and 5.1.5). 


ie Bee 


Numeric “approximately equal to” operator (Section 2.6.4). 


Relational “exactly equal to” string operator (Section 5.1.5). 


The decimal values 128 through 255 can appear in character strings. For most practical purposes, the characters 
represented by N (0 2 N 2 127) and N + 128 are the same. However, the characters returned from the function 
CHRS(N) and CHR$(N + 128) do not test as equal when compared. These values may also influence device-dependent 
operations. (See the RSTS/E Programming Manual.) 
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BASIC-PLUS Character Set 


-_~ Decimal ASCII Decimal ASCII RSTS | Decimal ASCII RSTS 
Value Character RSTS Usage Value Character Usage | Value Character Usage 


FILL character 


CTRL/C 
CTRL/D 


i) —" 1) a . 


BELL (CTRL/G) 
BACKSPACE 
HORIZONTAL TAB 
LINE FEED 
VERTICAL TAB 
FORM FEED (CTRL/L) 
CARRIAGE RETURN 


— 
Ret MOOD: (ad! OS GA a CoD ee 


. Grave accent 


—" 
— 
WO: CO 7 Gh Gr a 


CTRL/O 
XON (CTRL/Q) 


X OFF (CTRL/S) 


Oe 
Oo onzaa in h W bho 


CTRL/U 


Nw NHN WN 
WN 


i) 
a 


CTRL/Z 
ESCAPE? 


NNN NY WN LYN 
Oo ONAN 


Ww 
— 
a Taam cS Tals” TS Te a etc Rs Di NE, Go, 


WW W 
& W bo 


X 
y 
Z 
| 


WWW Ww 
COOon NN 


Vertical Line 


W 
\o 


~ Tilde 
DEL RUBOUT 


- 4 
—_ <> 


mS 
> 
? 
@ 
A 
B 
. 
D 
e 
F 
G 
H 
30 | 
J 
K 
L 
M 
N 
O 
P 
Q 
R 
S 
T 
U 


a 
nN 


a 1 ALTMODE (ASCII 125) or PREFIX (ASCII 126) keys which appear on some terminals are translated internally into ESCAPE. 
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APPENDIX E 
RSTS/E FLOATING-POINT AND INTEGER FORMATS 


E.1 FLOATING-POINT FORMATS 

RSTS/E systems use two standard floating-point packages: the single precision, 2-word package or the double precision, 
4-word package. The determination of which package will be used is made by the system manager at the time the 
BASIC-PLUS runtime system is generated. 


The single precision format provides economical storage, while the double precision format is used for high accuracy. 
The single precision format provides up to 24 bits of approximately seven decimal digits of accuracy. The magnitude 


range lies between .29 * 10 “(-38) and 1.7 * 10 *(38). Double precision calculations have a precision of 56 bits of 
approximately 16 decimal digits, with magnitudes in the same range as for single precision format. 


14 7 6 


pbs 


SINGLE PRECISION FORMAT (2 WORD) 


© 


14 7 6 0 


15 


word+2: low-order mantissa 
word+4: lower-order mantissa 
word+6: lowest-order mantissa 


DOUBLE PRECISION FORMAT (4 WORD) 


The exponent is stored in excess 128 (2003) notation. Exponents from - 127 to +127 are represented by the binary 
equivalent of 1 through 255 (1 through 3773). Fractions are represented in sign magnitude notation with the binary 
radix point to the left. Numbers are assumed to be normalized and, therefore, the most significant bit is not stored 
because it is redundant (this is called “hidden bit normalization’”’); it is always a | unless the exponent is 0 in which case 
it is assumed to be O. The value 0 is therefore represented by two or four words of 0’s. For example: +1 would be 
represented by: 


E-] 


RSTS Floating-Point and Integer Formats 


word: 040200 : 
wordt2: 000000 
in the 2-word format, or: 
Z 
word: 040200 
word+2: 000000 
word+4: 000000 : 
wordt6: 000000 
in the 4-word format. -5 would be: 
word: 140640 
word+2: 000000 
in the 2-word format, or: 

Fou 
word: 140640 es 
word+2: 000000 
wordt4: 000000 
wordt6: 000000 

in the 4-word format. 
While it is generally possible to run programs written on one RSTS system on another RSTS system, certain restrictions 
apply if the math packages are not the same. These are: 


1. Programs depending on 4-word accuracy cannot be run with the 2-word package. 

2. .BAC compiled programs cannot be interchanged. The program source file must be recompiled. 

3. Floating-point virtual core array file formats are not compatible between math packages. 

4. Programs using the Record I/O functions CVT$F and CVTF$ are not compatible between math packages. 


E.2 INTEGER FORMAT 


15 14 0 


_~ 


Integers are stored in a 2’s complement representation. Integer values must be in the range -32768 to +32767. For 
example: 


+22 = 000026, 
-7=1777718 


As a rule, an integer value is assumed by RSTS only where a constant or variable name is followed by a % character. ~ 
Otherwise, constants and variables are assumed to be floating-point values. 
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